Re: [roland.winkler@physik.uni-erlangen.de: documentation bug: customization type `option']

[Per Abrahamsen <abraham@dina.kvl.dk>]

[-- Attachment #1: Type: text/plain, Size: 1648 bytes --]

Alex Schroeder <alex@emacswiki.org> 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.


[-- Attachment #2: Type: message/rfc822, Size: 5691 bytes --]

From: Per Abrahamsen <abraham@dina.kvl.dk>
To: rms@gnu.org
Cc: emacs-devel@gnu.org
Subject: Re: Creating recursive customization types / widgets
Date: Wed, 03 Dec 2003 16:26:30 +0100
Message-ID: <rjhe0hapnd.fsf@sheridan.dina.kvl.dk>

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  <abraham@dina.kvl.dk>

	* 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


[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel