From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Per Abrahamsen Newsgroups: gmane.emacs.devel Subject: Re: [roland.winkler@physik.uni-erlangen.de: documentation bug: customization type `option'] Date: Wed, 07 Jul 2004 18:34:23 +0200 Organization: The Church of Emacs Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: References: <871xjuojfl.fsf@emacswiki.org> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: sea.gmane.org 1089218110 23056 80.91.224.253 (7 Jul 2004 16:35:10 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 7 Jul 2004 16:35:10 +0000 (UTC) Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Wed Jul 07 18:34:46 2004 Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1BiFNd-0000IY-00 for ; Wed, 07 Jul 2004 18:34:45 +0200 Original-Received: from lists.gnu.org ([199.232.76.165]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1BiFNd-0004eK-00 for ; Wed, 07 Jul 2004 18:34:45 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1BiFPh-0004Zs-VD for emacs-devel@quimby.gnus.org; Wed, 07 Jul 2004 12:36:54 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.33) id 1BiFPd-0004W8-RY for emacs-devel@gnu.org; Wed, 07 Jul 2004 12:36:49 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.33) id 1BiFPd-0004VN-4q for emacs-devel@gnu.org; Wed, 07 Jul 2004 12:36:49 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1BiFPd-0004VH-20 for emacs-devel@gnu.org; Wed, 07 Jul 2004 12:36:49 -0400 Original-Received: from [80.91.224.249] (helo=main.gmane.org) by monty-python.gnu.org with esmtp (Exim 4.34) id 1BiFNK-0006xp-U2 for emacs-devel@gnu.org; Wed, 07 Jul 2004 12:34:27 -0400 Original-Received: from list by main.gmane.org with local (Exim 3.35 #1 (Debian)) id 1BiFNK-0006Qc-00 for ; Wed, 07 Jul 2004 18:34:26 +0200 Original-Received: from sheridan.dina.kvl.dk ([130.225.40.227]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Wed, 07 Jul 2004 18:34:26 +0200 Original-Received: from abraham by sheridan.dina.kvl.dk with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Wed, 07 Jul 2004 18:34:26 +0200 X-Injected-Via-Gmane: http://gmane.org/ Mail-Followup-To: emacs-devel@gnu.org Original-To: emacs-devel@gnu.org Original-Lines: 220 Original-X-Complaints-To: usenet@sea.gmane.org X-Gmane-NNTP-Posting-Host: sheridan.dina.kvl.dk X-Face: +kRV2]2q}lixHkE{U)mY#+6]{AH=yN~S9@IFiOa@X6?GM|8MBp/ Mail-Copies-To: nobody User-Agent: Gnus/5.110002 (No Gnus v0.2) Emacs/21.3 (gnu/linux) Cancel-Lock: sha1:h/M8KUO3aXtiqJXmBI8tvwN5ruE= 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: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:25528 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:25528 --=-=-= Alex Schroeder 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. --=-=-= Content-Type: message/rfc822 Content-Disposition: inline X-From-Line: abraham@dina.kvl.dk Wed Dec 3 16:26:30 2003 Return-Path: Delivered-To: abraham@dina.kvl.dk Received: by sheridan.dina.kvl.dk (Postfix, from userid 304) id 155A313CFC; Wed, 3 Dec 2003 16:26:30 +0100 (CET) To: rms@gnu.org Cc: emacs-devel@gnu.org Subject: Re: Creating recursive customization types / widgets Organization: The Church of Emacs X-Face: +kRV2]2q}lixHkE{U)mY#+6]{AH=yN~S9@IFiOa@X6?GM|8MBp/ References: From: Per Abrahamsen Date: Wed, 03 Dec 2003 16:26:30 +0100 In-Reply-To: (Richard Stallman's message of "Tue, 02 Dec 2003 23:46:12 -0500") Message-ID: User-Agent: Gnus/5.1003 (Gnus v5.10.3) Emacs/21.3 (gnu/linux) Lines: 106 Xref: sheridan.dina.kvl.dk emacs.devel:13953 MIME-Version: 1.0 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 * 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 --=-=-= Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ Emacs-devel mailing list Emacs-devel@gnu.org http://lists.gnu.org/mailman/listinfo/emacs-devel --=-=-=--