Re: no doc for `group' in custom :type

Re: no doc for `group' in custom :type

[Richard Stallman]

Does anyone remember what `group' is for, so as to document it?

X-Spam-Status: No, score=0.0 required=5.0 tests=UNPARSEABLE_RELAY 
	autolearn=failed version=3.1.0
From: "Drew Adams" <drew.adams@oracle.com>
To: "Emacs-Pretest-Bug" <emacs-pretest-bug@gnu.org>
Date: Fri, 8 Jun 2007 11:34:59 -0700
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"
Subject: no doc for `group' in custom :type

In the Elisp manual, I find nothing about `group' as a type
symbol. There is an example, in node Simple Types, that uses `group'
when explaining type symbol `alist', but `group' is explained nowhere.

This is the example: 

 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
            "Each element is a list of the form (KEY VALUE)."
            :type '(alist :value-type (group integer)))

The only explanation is this, given in passing:

     The `group' widget is used here instead of `list' only because the
     formatting is better suited for the purpose.

What formatting? How is a reader supposed to understand this? Why does
the manual speak of "widget" here, anyway? `group' should be explained
as a symbol that you can use when defining a :type value in a
`defcustom', just as `alist' and :value-type are explained in that
context.

`group' is not something specific to `alist', in any case. I find
this, for instance, in file `cus-edit.el' (as well as many other uses
of `group').

 :type '(repeat (group (regexp :tag "Match") (sexp :tag "Type")))

It seems that it is quite common to use `group' in `defcustom' :type
specs, but it is not documented. If users are to understand `group'
only by reading the widget doc, then there should at least be a cross
reference to that doc here. How can Elisp programmers know about using
`group' in :type specs if it is not documented?

Furthermore, if you do go to the trouble of looking up `group' in the
Widget manual, this is all you find (in node `group'):

 The `group' Widget
 ------------------

 This widget simply group other widgets together.

   Syntax:

     TYPE ::= (group [KEYWORD ARGUMENT]... TYPE...)

   The value is a list, with one member for each TYPE.

There are no other occurrences of "group" in the Widget manual. And
that node certainly doesn't teach us anything about formatting, or how
the formatting is different from using `list' in :type.

Please document `group' fully in the context of `defcustom' :type
specs, explaining how it can be used and how it differs from using
`list'.



In GNU Emacs 22.1.50.1 (i386-mingw-nt5.1.2600)
 of 2007-05-22 on LENNART-69DE564
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --cflags -Ic:/g/include'




_______________________________________________
emacs-pretest-bug mailing list
emacs-pretest-bug@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-pretest-bug

Re: no doc for `group' in custom :type

[Richard Stallman]

[I sent this message a month ago but did not get a response.]

Does anyone remember what `group' is for, so as to document it?

X-Spam-Status: No, score=0.0 required=5.0 tests=UNPARSEABLE_RELAY 
	autolearn=failed version=3.1.0
From: "Drew Adams" <drew.adams@oracle.com>
To: "Emacs-Pretest-Bug" <emacs-pretest-bug@gnu.org>
Date: Fri, 8 Jun 2007 11:34:59 -0700
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"
Subject: no doc for `group' in custom :type

In the Elisp manual, I find nothing about `group' as a type
symbol. There is an example, in node Simple Types, that uses `group'
when explaining type symbol `alist', but `group' is explained nowhere.

This is the example: 

 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
            "Each element is a list of the form (KEY VALUE)."
            :type '(alist :value-type (group integer)))

The only explanation is this, given in passing:

     The `group' widget is used here instead of `list' only because the
     formatting is better suited for the purpose.

What formatting? How is a reader supposed to understand this? Why does
the manual speak of "widget" here, anyway? `group' should be explained
as a symbol that you can use when defining a :type value in a
`defcustom', just as `alist' and :value-type are explained in that
context.

`group' is not something specific to `alist', in any case. I find
this, for instance, in file `cus-edit.el' (as well as many other uses
of `group').

 :type '(repeat (group (regexp :tag "Match") (sexp :tag "Type")))

It seems that it is quite common to use `group' in `defcustom' :type
specs, but it is not documented. If users are to understand `group'
only by reading the widget doc, then there should at least be a cross
reference to that doc here. How can Elisp programmers know about using
`group' in :type specs if it is not documented?

Furthermore, if you do go to the trouble of looking up `group' in the
Widget manual, this is all you find (in node `group'):

 The `group' Widget
 ------------------

 This widget simply group other widgets together.

   Syntax:

     TYPE ::= (group [KEYWORD ARGUMENT]... TYPE...)

   The value is a list, with one member for each TYPE.

There are no other occurrences of "group" in the Widget manual. And
that node certainly doesn't teach us anything about formatting, or how
the formatting is different from using `list' in :type.

Please document `group' fully in the context of `defcustom' :type
specs, explaining how it can be used and how it differs from using
`list'.



In GNU Emacs 22.1.50.1 (i386-mingw-nt5.1.2600)
 of 2007-05-22 on LENNART-69DE564
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --cflags -Ic:/g/include'




_______________________________________________
emacs-pretest-bug mailing list
emacs-pretest-bug@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-pretest-bug

RE: no doc for `group' in custom :type

[Drew Adams]

In GNU Emacs 22.1.1 (i386-mingw-nt5.1.2600) of 2007-06-02 on RELEASE:

The doc bug described below was apparently fixed by just adding an
explanation of the type `group' (in node Common Keywords).

However, the example that should have been changed to use `list' instead of
`group' still uses `group'. See type `alist' in node Simple Types.

And this problematic sentence was left in the doc:

 "The `group' widget is used here instead of `list' only because the
 formatting is better suited for the purpose."

I still don't understand what that sentence means - why is the formatting
(what formatting?) better for `group' in this example than for `list'?

I think that `list' is preferable here because the cdr is of type list -
regardless of any formatting. That is, `list' says something about the type
of the alist value, whereas `group' does not.

See below for more background.

> From: Per Abrahamsen Sent: Wednesday, August 01, 2007 9:19 AM
>
> Basically, there are two "levels" of widgets.  The low level widgets
> which provide the "inline form editing functionality" and the sexp
> widgets which are suposed to represent Lisp s-expressions.  The sexp
> widgets are build on top of the low level widgets.
>
> In theory, if you are building a form where the data represents
> something other than s-expressions, you should use the low level
> widgets, while if what you are building is some textual representation
> of s-expressions you should use the sexp widgets.
>
> The custom types, by nature, always represent sexps.  So only the sexp
> expressions should be used.
>
> In practise, the distinction is muddy, as the low level widgets
> naturally also must use s-expressions to hold their value.  So
> whatever looks best tend to be used.
>
> The group widget is a low level widget that represent allows you to
> handle a group of widgets as a single widget.  The value of the group
> widget is represented as a list whose members are the values of the
> child widgets.  Which happens to be exactly the same as how the "list"
> widget represent its value.  So the two are almost identical.
>
> The difference is in the :format attribute, one of them shows both the
> tag and the value, while the other does not.  I don't remember which
> is which.
>
>
> On 7/30/07, Richard Stallman <rms@gnu.org> wrote:
> > Do you remember what the custom type `group' is for?  I would like to
> > document it.
> >
> > X-Spam-Status: No, score=0.0 required=5.0 tests=UNPARSEABLE_RELAY
> >         autolearn=failed version=3.1.0
> > From: "Drew Adams" <drew.adams@oracle.com>
> > To: "Emacs-Pretest-Bug" <emacs-pretest-bug@gnu.org>
> > Date: Fri, 8 Jun 2007 11:34:59 -0700
> > MIME-Version: 1.0
> > Content-Type: text/plain;
> >         charset="iso-8859-1"
> > Subject: no doc for `group' in custom :type
> >
> > In the Elisp manual, I find nothing about `group' as a type
> > symbol. There is an example, in node Simple Types, that uses `group'
> > when explaining type symbol `alist', but `group' is explained nowhere.
> >
> > This is the example:
> >
> >  (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
> >             "Each element is a list of the form (KEY VALUE)."
> >             :type '(alist :value-type (group integer)))
> >
> > The only explanation is this, given in passing:
> >
> >      The `group' widget is used here instead of `list' only because the
> >      formatting is better suited for the purpose.
> >
> > What formatting? How is a reader supposed to understand this? Why does
> > the manual speak of "widget" here, anyway? `group' should be explained
> > as a symbol that you can use when defining a :type value in a
> > `defcustom', just as `alist' and :value-type are explained in that
> > context.
> >
> > `group' is not something specific to `alist', in any case. I find
> > this, for instance, in file `cus-edit.el' (as well as many other uses
> > of `group').
> >
> >  :type '(repeat (group (regexp :tag "Match") (sexp :tag "Type")))
> >
> > It seems that it is quite common to use `group' in `defcustom' :type
> > specs, but it is not documented. If users are to understand `group'
> > only by reading the widget doc, then there should at least be a cross
> > reference to that doc here. How can Elisp programmers know about using
> > `group' in :type specs if it is not documented?
> >
> > Furthermore, if you do go to the trouble of looking up `group' in the
> > Widget manual, this is all you find (in node `group'):
> >
> >  The `group' Widget
> >  ------------------
> >
> >  This widget simply group other widgets together.
> >
> >    Syntax:
> >
> >      TYPE ::= (group [KEYWORD ARGUMENT]... TYPE...)
> >
> >    The value is a list, with one member for each TYPE.
> >
> > There are no other occurrences of "group" in the Widget manual. And
> > that node certainly doesn't teach us anything about formatting, or how
> > the formatting is different from using `list' in :type.
> >
> > Please document `group' fully in the context of `defcustom' :type
> > specs, explaining how it can be used and how it differs from using
> > `list'.
> >
> >
> >
> > In GNU Emacs 22.1.50.1 (i386-mingw-nt5.1.2600)
> >  of 2007-05-22 on LENNART-69DE564
> > Windowing system distributor `Microsoft Corp.', version 5.1.2600
> > configured using `configure --with-gcc (3.4) --cflags -Ic:/g/include'
> >
> >
> >
> >
> > _______________________________________________
> > emacs-pretest-bug mailing list
> > emacs-pretest-bug@gnu.org
> > http://lists.gnu.org/mailman/listinfo/emacs-pretest-bug
> >
> >
> >
> >
>

Re: no doc for `group' in custom :type

[Richard Stallman]

    The doc bug described below was apparently fixed by just adding an
    explanation of the type `group' (in node Common Keywords).

I do not see that.  Can you please SHOW the text you are referring
to rather than describing it?

Anyway that is the wrong place to explain a type.
So I just wrote text to expain `group' in Composite Types.
  
    However, the example that should have been changed to use `list' instead of
    `group' still uses `group'. See type `alist' in node Simple Types.

Do you mean this?

    @smallexample
    (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
      "Each element is a list of the form (KEY VALUE)."
      :type '(alist :value-type (group integer)))
    @end smallexample

I think it is ok to use `group' if that looks better.

RE: no doc for `group' in custom :type

[Drew Adams]

>     The doc bug described below was apparently fixed by just
>     adding an explanation of the type `group' (in node Common
>     Keywords).
>
> I do not see that.  Can you please SHOW the text you are referring
> to rather than describing it?

My bad. I thought you had added an explanation of `group' in node Common
Keywords, but I was mistaken.

> Anyway that is the wrong place to explain a type.
> So I just wrote text to expain `group' in Composite Types.

I can't find where such an explanation was added, so the bug seems to be
still outstanding as it was originally reported: no explanation of type
`group'.

The only occurrence of `group' I see in node Composite Types (latest CVS
texinfo) is this:

@item :indent @var{columns}
Indent this item by @var{columns} columns.  The indentation is used for
@samp{%n}, and automatically for group names, for checklists and radio
buttons, and for editable lists.  It affects the whole of the
item except for the first line.

That doesn't explain what the type `group' is.

>     However, the example that should have been changed to use
>     `list' instead of `group' still uses `group'. See type `alist'
>     in node Simple Types.
>
> Do you mean this?
>
>     @smallexample
>     (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
>       "Each element is a list of the form (KEY VALUE)."
>       :type '(alist :value-type (group integer)))
>     @end smallexample

Yes.

> I think it is ok to use `group' if that looks better.

I guess you mean that a `group' type looks better than a `list' type in a
Customize buffer. Maybe so. If you substitute `list' for `group' in that
example, the only difference is that `List:' is added before `Integer: 1'.
OK, that's looks a little better.

However, it is less clear, especially in an example intended to explain  use
of the `alist' type with a list as the value component. `list' should be
used here because the type is a list of one integer - the type spec should
be written (list integer).

And the mysterious sentence still follows the example:

 The @code{group} widget is used here instead of @code{list} only
 because the formatting is better suited for the purpose.

It's not clear here what formatting is meant - the formatting in the
Customize buffer.

Per my reading of Per's mail, `group' is for widgets, rather than being
intended as a customizaton type. He said:

> The custom types, by nature, always represent sexps.
> So only the sexp expressions should be used.

That means `list', not `group' should be used, AFAICT.

I don't understand why a discussion of Customize types would introduce
`group' at all, if it is for widgets but not for Customize types.

And if `group' is also intended for Customize types, then it needs to be
documented. This example uses the type `group', but it was never introduced.

Re: no doc for `group' in custom :type

[Richard Stallman]

    > Anyway that is the wrong place to explain a type.
    > So I just wrote text to expain `group' in Composite Types.

    I can't find where such an explanation was added, so the bug seems to be

It isn't checked in yet.  I am busy!  Stop hassling me because
things take time!

RE: no doc for `group' in custom :type

[Drew Adams]

>     > Anyway that is the wrong place to explain a type.
>     > So I just wrote text to expain `group' in Composite Types.
>
>     I can't find where such an explanation was added, so the bug
>     seems to be
>
> It isn't checked in yet.  I am busy!  Stop hassling me because
> things take time!

Uh, du calme.

Gee, I'm sorry, but you could have simply mentioned that when I pinged about
it two days ago. That would have saved the follow-up email that exasperated
you further.

If it's not yet fixed, that's fine. I thought that you were saying that it
was fixed, and I didn't see the fix.

I reported the bug on June 8, and I pinged about it on November 24. I
wouldn't call that hassling anyone.