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 <address@hidden> 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" <address@hidden>
> > To: "Emacs-Pretest-Bug" <address@hidden>
> > 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
> > address@hidden
> > http://lists.gnu.org/mailman/listinfo/emacs-pretest-bug
> >
> >
> >
> >
>