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

[Alex Schroeder]

Richard Stallman <address@hidden> writes:

> In bibtex.el the declaration of bibtex-user-optional-fields as a
> customizable user option variable contains the custamization type
> `option'. It seems to me that this custamization type is not
> documented anywhere. I can't find it in the appropriate part of the
> elisp manual (nodes `Simple Types' or `Composite Types') nor can I
> find it in the info file for the emacs widget library.
>
> The particular thing I want to know is whether (how) one can specify
> the default value `unselected' for the checkbox of an option.

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

default
function-link
variable-link
file-link
emacs-library-link
emacs-commentary-link
option
radio-button
insert-button
delete-button
visibility
documentation-link
documentation-string
other
coding-system
restricted-sexp
float
lazy
my-list
sexp-list
plist
alist
radio
color

As for the question:  The source says that an option is just an
inlined checklist:

(define-widget 'option 'checklist
  "An widget with an optional item."
  :inline t)

Thus: "The checklist widget will match a list whose elements all match
at least one of the specified TYPE arguments."

It seems to me that an unselected option would therefore have an
unmatched value.


(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")
                        (option (group :inline t
                                       :extra-offset -4
                                       (choice :tag "Init" :value ""
                                               string
                                               function))))))

Therefore:

(setq bibtex-user-optional-fields '(("field" "comment" "foo")))
(customize-option 'bibtex-user-optional-fields)

  Make sense, "foo" matches the string choice.

(setq bibtex-user-optional-fields '(("field" "comment" bar)))
(customize-option 'bibtex-user-optional-fields)

  Here's the strange thing: this matches the function choice
  even though (functionp "foo") is nil

In fact, 0, t, nil -- all of them are recognized as a function!  When
you try to set the function widget to any of these values
interactively, you will get an error.

I'm not sure what to do here.  Maybe we can make the function widget
more selective, but it might break -- eg. you might want to force
users to only choose defined functions interactively, but when the
customization is saved and loaded in another session, you want to be
able to show the user the widget, even if the function is not defined
anymore.  Thus, I suggest no change.

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)

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.

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)

(setq bibtex-user-optional-fields '(("field" "comment" nil)))
(customize-option 'bibtex-user-optional-fields)

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?

Alex.
-- 
.O.  http://www.emacswiki.org/alex/
..O  Schroeder's fourth law:
OOO  None of your friends and coworkers share your taste in music.