[roland.winkler@physik.uni-erlangen.de: documentation bug: customization type `option']

[roland.winkler@physik.uni-erlangen.de: documentation bug: customization type `option']

[Richard Stallman]

Can someone help Roland with this?

------- Start of forwarded message -------
From: Roland Winkler <roland.winkler@physik.uni-erlangen.de>
Date: Tue, 29 Jun 2004 13:21:48 +0200
To: emacs-pretest-bug@gnu.org
X-Spam-DCC: rrze-dcc:moritz72 1202; Body=1 Fuz1=1 Fuz2=1
X-Spam-RBL: 
X-Spam-Eval: ham 
X-Spam-RRZE-Info: Diese Mail wurde einer automatischen Spam-Analyse unterzogen,
	siehe: http://www.rrze.uni-erlangen.de/dienste/e-mail/spam-analyse/
Subject: documentation bug: customization type `option'
Sender: emacs-pretest-bug-bounces+rms=gnu.org@gnu.org
X-Spam-Status: No, hits=0.5 required=5.0
	tests=RCVD_IN_ORBS
	version=2.55
X-Spam-Level: 
X-Spam-Checker-Version: SpamAssassin 2.55 (1.174.2.19-2003-05-19-exp)

Symptoms:




In GNU Emacs 21.3.50.6 (i686-pc-linux-gnu, X toolkit, Xaw3d scroll bars)
 of 2004-06-06 on tfkp07
configured using `configure '--prefix=/nfs/common' '--libexecdir=/nfs/common/lib' '--bindir=/nfs/common/lib/emacs/21.1/bin/i686-Linux' '--mandir=/nfs/common/share/man' '--infodir=/nfs/common/share/info' '--with-gcc' '--with-pop' '--with-x' '--with-x-toolkit=athena' '--x-libraries=/usr/X11R6/lib''

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: POSIX
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: en_US
  locale-coding-system: iso-latin-1
  default-enable-multibyte-characters: t


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.

Thanks,

Roland


PS: I know, I am the maintainer of bibtex.el... But the declaration
of bibtex-user-optional-fields is due to one of my predecessors.


_______________________________________________
Emacs-pretest-bug mailing list
Emacs-pretest-bug@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-pretest-bug
------- End of forwarded message -------

Re: [roland.winkler@physik.uni-erlangen.de: documentation bug: customization type `option']

[Alex Schroeder]

Richard Stallman <rms@gnu.org> 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.

Re: [roland.winkler@physik.uni-erlangen.de: 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

Re: [roland.winkler@physik.uni-erlangen.de: documentation bug: customization type `option']

[Richard Stallman]

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

If you would like these to be better documented,
I recommend adding information to their doc strings.
It is not worth writing text in the manual for internal facilities.
Writing good manual text is hard work, and I don't want to do it
when it's not needed.

Re: [roland.winkler@physik.uni-erlangen.de: documentation bug: customization type `option']

[Miles Bader]

On Sat, Jul 03, 2004 at 02:21:19PM -0400, Richard Stallman wrote:
> It is not worth writing text in the manual for internal facilities.
> Writing good manual text is hard work, and I don't want to do it
> when it's not needed.

What about just saying somethign like `some other widget types exist, and are
documented in their doc-string, for instance: <list of widget types>'.

[Of course some of these widgets may be undocumented for good reason --
e.g., they are incompletely implemented or something (perhaps working only
in the specific case where they are used).]

-Miles
-- 
We live, as we dream -- alone....

Re: [roland.winkler@physik.uni-erlangen.de: documentation bug: customization type `option']

[Roland Winkler]

On Sat, Jul 03, 2004 at 02:21:19PM -0400, Richard Stallman wrote:
> It is not worth writing text in the manual for internal facilities.
> Writing good manual text is hard work, and I don't want to do it
> when it's not needed.

Maybe this depends on the point of view. Being the maintainer of a
high-level package I feel like the user of the low-level stuff such as
widgets. So I am grateful when the low-level stuff is well documented
and I need not spend too much time digging in its source code.

On Sat Jul 3 2004 Miles Bader wrote:
> What about just saying somethign like `some other widget types
> exist, and are documented in their doc-string, for instance: <list
> of widget types>'.
> 
> [Of course some of these widgets may be undocumented for good
> reason -- e.g., they are incompletely implemented or something
> (perhaps working only in the specific case where they are used).]

I think that's a good idea. I spent a little time trying to make
sure that I didn't overlook anything in the info files. So if
there had been such a remark, it would have saved me some time.

Roland

Re: [roland.winkler@physik.uni-erlangen.de: documentation bug: customization type `option']

[Per Abrahamsen]

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

Alex Schroeder <alex@emacswiki.org> writes:

> default

This is very low level, and should be documented in "how to write new
basic widgets".

> function-link
> variable-link
> file-link
> emacs-library-link
> emacs-commentary-link

They are useful for "ordinary" users of the widget (but not custom)
library, and ought to be documented, if nothing else, then to make
people aware they exists.

> option

Can be useful for custom types, should be documented.

> radio-button
> insert-button
> delete-button

These are internal helper widgets, used to implement the
"radio-choice" and "editable-list" widgets.  Should not be documented.

> visibility
> documentation-link
> documentation-string

Helper widgets for doc strings, may be generally useful for other
users of the widget library.  Should be documented.

> other

>From the doc string, seems like it should be documented together with
the "choice" widget.

> coding-system

I'm not sure, but I think it is intended to be used as a custom type.
If so, it should be documented there.

> restricted-sexp

RMS wrote this, I believe it is also intended as a custom type (and
should be documented thus).

> float

Apparently like "number" and "integer".  Should be documented the same
place. 

> lazy

I wrote documentation for this, but it was apparently never checked
in.  See below.

> my-list
> sexp-list

These are examples within the doc string of "lazy", you lazy grepper :)

> plist
> alist
> radio

These are intended as custom types, and should be documented.  I'm
surprised "radio" isn't.

> color

A helper widget for custom, which could be generally useful.  Should
be documented.


[-- Attachment #2: Type: message/rfc822, Size: 5691 bytes --]

From: Per Abrahamsen <abraham@dina.kvl.dk>
To: rms@gnu.org
Cc: emacs-devel@gnu.org
Subject: Re: Creating recursive customization types / widgets
Date: Wed, 03 Dec 2003 16:26:30 +0100
Message-ID: <rjhe0hapnd.fsf@sheridan.dina.kvl.dk>

Here is documentation patch describing the use of the new widget.  Is
it ok to commit that, and the lazy widget code itself, to CVS?

2003-12-03  Per Abrahamsen  <abraham@dina.kvl.dk>

	* customize.texi (Defining New Types): Document use of the
        `lazy' widget. 

*** customize.texi.~1.36.~	2003-11-30 14:59:10.000000000 +0100
--- customize.texi	2003-12-03 16:18:56.000000000 +0100
***************
*** 1,6 ****
  @c -*-texinfo-*-
  @c This is part of the GNU Emacs Lisp Reference Manual.
! @c Copyright (C) 1997, 1998, 1999, 2000, 2002 Free Software Foundation, Inc.
  @c See the file elisp.texi for copying conditions.
  @setfilename ../info/customize
  @node Customization, Loading, Macros, Top
--- 1,6 ----
  @c -*-texinfo-*-
  @c This is part of the GNU Emacs Lisp Reference Manual.
! @c Copyright (C) 1997, 1998, 1999, 2000, 2002, 2003 Free Software Foundation, Inc.
  @c See the file elisp.texi for copying conditions.
  @setfilename ../info/customize
  @node Customization, Loading, Macros, Top
***************
*** 373,378 ****
--- 373,379 ----
  * Composite Types::
  * Splicing into Lists::
  * Type Keywords::
+ * Defining New Types::
  @end menu
  
  All customization types are implemented as widgets; see @ref{Top, ,
***************
*** 1056,1061 ****
--- 1057,1123 ----
  @end ignore
  @end table
  
+ @node Defining New Types
+ @subsection Defining New Types
+ 
+ In the previous sections we have described how to construct elaborate
+ type specifications for @code{defcustom}.  In some cases you may want to
+ give such a type specification a name.  The obvious case is when you are
+ using the same type for many user options, rather than repeat the
+ specification for each option, you can give the type specification a
+ name once, and use that name each @code{defcustom}.  The other case is
+ when a user option accept a recursive datastructure.  To make it
+ possible for a datatype to refer to itself, it needs to have a name.
+ 
+ Since custom types are implemented as widgets, the way to define a new
+ customize type is to define a new widget.  We are not going to describe
+ the widget interface here in details, see @ref{Top, , Introduction,
+ widget, The Emacs Widget Library}, for that.  Instead we are going to
+ demonstrate the minimal functionality needed for defining new customize
+ types by a simple example.
+ 
+ @example
+ (define-widget 'binary-tree-of-string 'lazy
+   "A binary tree made of cons-cells and strings."
+   :offset 4
+   :tag "Node"
+   :type '(choice (string :tag "Leaf" :value "")
+                  (cons :tag "Interior"
+                        :value ("" . "") 
+                        binary-tree-of-string
+                        binary-tree-of-string)))
+ 
+ (defcustom foo-bar ""
+   "Sample variable holding a binary tree of strings."
+   :type 'binary-tree-of-string)
+ @end example
+ 
+ The function to define a new widget is name @code{define-widget}.  The
+ first argument is the symbol we want to make a new widget type.  The
+ second argument is a symbol representing an existing widget, the new
+ widget is going to be defined in terms of difference from the existing
+ widget.  For the purpose of defining new customization types, the
+ @code{lazy} widget is perfect, because it accept a @code{:type} keyword
+ argument with the same syntax as the keyword argument to
+ @code{defcustom} with the same name.  The third argument is a
+ documentation string for the new widget.  You will be able to see that
+ string with the @kbd{M-x widget-browse @key{ret} binary-tree-of-string
+ @key{ret}} command.  
+ 
+ After these mandatory arguments follows the keyword arguments.  The most
+ important is @code{:type}, which describes the datatype we want to match
+ 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 are there to ensure that child nodes are
+ indented four spaces relatively 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. 
+ 
  @ignore
     arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2
  @end ignore


[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: [roland.winkler@physik.uni-erlangen.de: documentation bug: customization type `option']

[Richard Stallman]

    > lazy

    I wrote documentation for this, but it was apparently never checked
    in.  See below.

The reason is that the name `lazy' is not suitable for its meaning.
I want the name to be changed before we document it.

Re: [roland.winkler@physik.uni-erlangen.de: documentation bug: customization type `option']

[Per Abrahamsen]

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

Richard Stallman <rms@gnu.org> writes:

>     > lazy
>
>     I wrote documentation for this, but it was apparently never checked
>     in.  See below.
>
> The reason is that the name `lazy' is not suitable for its meaning.
> I want the name to be changed before we document it.

'lazy' was the name you suggested.


[-- Attachment #2: Type: message/rfc822, Size: 3426 bytes --]

From: Richard Stallman <rms@gnu.org>
Cc: emacs-devel@gnu.org
Subject: Re: Creating recursive customization types / widgets
Date: Mon, 01 Dec 2003 23:17:54 -0500
Message-ID: <E1AR1z0-0000Uj-0c@fencepost.gnu.org>

The doc string for `child' is now clear, but it shows
that `child' is not the right name for it.

ISTR that there is a frequently used term for an object
whose value will be computed only when you actually refer to it,
but it has been so many years that I don't remember the term.
Is it "lazy"?  Maybe this type should be called `lazy'.

`delayed' is ok too.

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: [roland.winkler@physik.uni-erlangen.de: documentation bug: customization type `option']

[David Kastrup]

Per Abrahamsen <abraham@dina.kvl.dk> writes:

> Richard Stallman <rms@gnu.org> writes:
> 
> >     > lazy
> >
> >     I wrote documentation for this, but it was apparently never
> >     checked in.  See below.
> >
> > The reason is that the name `lazy' is not suitable for its
> > meaning.  I want the name to be changed before we document it.
> 
> 'lazy' was the name you suggested.
> 
> From: Richard Stallman <rms@gnu.org>
> Subject: Re: Creating recursive customization types / widgets
> Newsgroups: gmane.emacs.devel
> Cc: emacs-devel@gnu.org
> Date: Mon, 01 Dec 2003 23:17:54 -0500
> Reply-To: rms@gnu.org
> 
> The doc string for `child' is now clear, but it shows
> that `child' is not the right name for it.
> 
> ISTR that there is a frequently used term for an object
> whose value will be computed only when you actually refer to it,
> but it has been so many years that I don't remember the term.
> Is it "lazy"?  Maybe this type should be called `lazy'.
> 
> `delayed' is ok too.
> ----------

As a language feature, "lazy" is the most often used word as in "lazy
evaluation".  Scheme also has the noun "continuation" for what
amounts to an implementation of the concept.

I certainly think "lazy" appropriate.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: [roland.winkler@physik.uni-erlangen.de: documentation bug: customization type `option']

[Stefan]

> As a language feature, "lazy" is the most often used word as in "lazy
> evaluation".  Scheme also has the noun "continuation" for what
> amounts to an implementation of the concept.

No, continuations are something entirely different.  Scheme's operations to
handle laziness are "delay" and "force".


        Stefan

Re: [roland.winkler@physik.uni-erlangen.de: documentation bug: customization type `option']

[Richard Stallman]

    > The reason is that the name `lazy' is not suitable for its meaning.
    > I want the name to be changed before we document it.

    'lazy' was the name you suggested.

Sorry, I remembered I had asked you to change the name,
but didn't remember that you'd already done so.

Ok, let's add the documentation.