From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: RE: no doc for `group' in custom :type Date: Sat, 24 Nov 2007 16:50:08 -0800 Message-ID: References: <66a8b7a0708010919o38956bf6o844746290dad6a56@mail.gmail.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1195951845 21798 80.91.229.12 (25 Nov 2007 00:50:45 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 25 Nov 2007 00:50:45 +0000 (UTC) Cc: Emacs-Devel To: "Per Abrahamsen" , Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Nov 25 01:50:52 2007 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1Iw5hn-0004o6-IY for ged-emacs-devel@m.gmane.org; Sun, 25 Nov 2007 01:50:39 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Iw5hY-0002Fv-QT for ged-emacs-devel@m.gmane.org; Sat, 24 Nov 2007 19:50:24 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Iw5hU-0002DO-Iv for emacs-devel@gnu.org; Sat, 24 Nov 2007 19:50:20 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Iw5hT-0002CF-MY for emacs-devel@gnu.org; Sat, 24 Nov 2007 19:50:20 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Iw5hT-0002C7-Iq for emacs-devel@gnu.org; Sat, 24 Nov 2007 19:50:19 -0500 Original-Received: from agminet01.oracle.com ([141.146.126.228]) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1Iw5hP-0003Yt-EF; Sat, 24 Nov 2007 19:50:15 -0500 Original-Received: from rgmgw1.us.oracle.com (rgmgw1.us.oracle.com [138.1.186.110]) by agminet01.oracle.com (Switch-3.2.4/Switch-3.1.7) with ESMTP id lAP0oBM3006731; Sat, 24 Nov 2007 18:50:11 -0600 Original-Received: from rcsmt251.oracle.com (rcsmt251.oracle.com [148.87.90.196]) by rgmgw1.us.oracle.com (Switch-3.2.4/Switch-3.2.4) with ESMTP id lAONNDAe017733; Sat, 24 Nov 2007 17:50:10 -0700 Original-Received: from 141.144.88.84 by acsmt350.oracle.com with ESMTP id 3384670401195951805; Sat, 24 Nov 2007 16:50:05 -0800 X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) In-Reply-To: <66a8b7a0708010919o38956bf6o844746290dad6a56@mail.gmail.com> Importance: Normal X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3198 X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE X-detected-kernel: by monty-python.gnu.org: Linux 2.4-2.6 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:84091 Archived-At: 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 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" > > To: "Emacs-Pretest-Bug" > > 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 > > > > > > > > >