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

[Richard Stallman <rms@gnu.org>]

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