[Emacs-diffs] Changes to emacs/man/widget.texi,v

[Richard M. Stallman]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Richard M. Stallman <rms>       06/10/16 18:48:28

Index: widget.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/man/widget.texi,v
retrieving revision 1.37
retrieving revision 1.38
diff -u -b -r1.37 -r1.38
--- widget.texi 12 Oct 2006 06:37:11 -0000      1.37
+++ widget.texi 16 Oct 2006 18:48:28 -0000      1.38
@@ -480,11 +480,11 @@
 @comment  node-name,  next,  previous,  up
 @section Basic Types
 
-The syntax of a type specification is given below:
+This is the general syntax of a type specification:
 
 @example
-NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
-     |   NAME
address@hidden ::= (@var{name} address@hidden @var{argument}]... @var{args})
+     |   @var{name}
 @end example
 
 Where, @var{name} is a widget name, @var{keyword} is the name of a
@@ -724,7 +724,7 @@
 Syntax:
 
 @example
-TYPE ::= (link [KEYWORD ARGUMENT]...  [ VALUE ])
address@hidden ::= (link address@hidden @var{argument}]...  [ @var{value} ])
 @end example
 
 The @var{value}, if present, is used to initialize the @code{:value}
@@ -749,7 +749,7 @@
 Syntax:
 
 @example
-TYPE ::= (url-link [KEYWORD ARGUMENT]...  URL)
address@hidden ::= (url-link address@hidden @var{argument}]...  @var{url})
 @end example
 
 @findex address@hidden, and @code{url-link} widget}
@@ -764,7 +764,7 @@
 Syntax:
 
 @example
-TYPE ::= (info-link [KEYWORD ARGUMENT]...  ADDRESS)
address@hidden ::= (info-link address@hidden @var{argument}]...  @var{address})
 @end example
 
 When this link is invoked, the built-in Info reader is started on
@@ -778,7 +778,7 @@
 Syntax:
 
 @example
-TYPE ::= (push-button [KEYWORD ARGUMENT]...  [ VALUE ])
address@hidden ::= (push-button address@hidden @var{argument}]...  [ 
@var{value} ])
 @end example
 
 The @var{value}, if present, is used to initialize the @code{:value}
@@ -803,7 +803,7 @@
 Syntax:
 
 @example
-TYPE ::= (editable-field [KEYWORD ARGUMENT]... [ VALUE ])
address@hidden ::= (editable-field address@hidden @var{argument}]... [ 
@var{value} ])
 @end example
 
 The @var{value}, if present, is used to initialize the @code{:value}
@@ -863,7 +863,7 @@
 Syntax:
 
 @example
-TYPE ::= (menu-choice [KEYWORD ARGUMENT]... TYPE ... )
address@hidden ::= (menu-choice address@hidden @var{argument}]... @var{type} 
... )
 @end example
 
 The @var{type} argument represents each possible choice.  The widget's
@@ -904,13 +904,13 @@
 Syntax:
 
 @example
-TYPE ::= (radio-button-choice [KEYWORD ARGUMENT]...  TYPE ... )
address@hidden ::= (radio-button-choice address@hidden @var{argument}]...  
@var{type} ... )
 @end example
 
-The @var{type} argument represents each possible choice.  The widget's
-value will be that of the chosen @var{type} argument.  This widget will
-match any value matching at least one of the specified @var{type}
-arguments.
+The component types specify the choices, with one radio button for
+each.  The widget's value will be that of the chosen @var{type}
+argument.  This widget matches any value that matching at least one of
+the specified @var{type} arguments.
 
 The following extra properties are recognized.
 
@@ -971,7 +971,7 @@
 Syntax:
 
 @example
-ITEM ::= (item [KEYWORD ARGUMENT]... VALUE)
address@hidden ::= (item address@hidden @var{argument}]... @var{value})
 @end example
 
 The @var{value}, if present, is used to initialize the @code{:value}
@@ -986,7 +986,7 @@
 Syntax:
 
 @example
-ITEM ::= (choice-item [KEYWORD ARGUMENT]... VALUE)
address@hidden ::= (choice-item address@hidden @var{argument}]... @var{value})
 @end example
 
 The @var{value}, if present, is used to initialize the @code{:value}
@@ -1003,7 +1003,7 @@
 Syntax:
 
 @example
-TYPE ::= (toggle [KEYWORD ARGUMENT]...)
address@hidden ::= (toggle address@hidden @var{argument}]...)
 @end example
 
 The widget has two possible states, @samp{on} and @samp{off}, which
@@ -1039,7 +1039,7 @@
 Syntax:
 
 @example
-TYPE ::= (checkbox [KEYWORD ARGUMENT]...)
address@hidden ::= (checkbox address@hidden @var{argument}]...)
 @end example
 
 @node checklist, editable-list, checkbox, Basic Types
@@ -1050,7 +1050,7 @@
 Syntax:
 
 @example
-TYPE ::= (checklist [KEYWORD ARGUMENT]...  TYPE ... )
address@hidden ::= (checklist address@hidden @var{argument}]...  @var{type} ... 
)
 @end example
 
 The @var{type} arguments represent each checklist item.  The widget's
@@ -1108,7 +1108,7 @@
 Syntax:
 
 @example
-TYPE ::= (editable-list [KEYWORD ARGUMENT]... TYPE)
address@hidden ::= (editable-list address@hidden @var{argument}]... @var{type})
 @end example
 
 The value is a list, where each member represents one widget of type
@@ -1168,7 +1168,7 @@
 Syntax:
 
 @example
-TYPE ::= (group [KEYWORD ARGUMENT]... TYPE...)
address@hidden ::= (group address@hidden @var{argument}]... @var{type}...)
 @end example
 
 The value is a list, with one member for each @var{type}.
@@ -1201,7 +1201,7 @@
 The syntax for the @code{const} widget is:
 
 @example
-TYPE ::= (const [KEYWORD ARGUMENT]...  [ VALUE ])
address@hidden ::= (const address@hidden @var{argument}]...  [ @var{value} ])
 @end example
 
 The @var{value}, if present, is used to initialize the @code{:value}
@@ -1237,7 +1237,7 @@
 The syntax for the @code{sexp} widget is:
 
 @example
-TYPE ::= (sexp [KEYWORD ARGUMENT]...  [ VALUE ])
address@hidden ::= (sexp address@hidden @var{argument}]...  [ @var{value} ])
 @end example
 
 @deffn Widget sexp
@@ -1261,7 +1261,7 @@
 The syntax for all the atoms are:
 
 @example
-TYPE ::= (NAME [KEYWORD ARGUMENT]...  [ VALUE ])
address@hidden ::= (@var{construct} address@hidden @var{argument}]...  [ 
@var{value} ])
 @end example
 
 The @var{value}, if present, is used to initialize the @code{:value}
@@ -1331,10 +1331,10 @@
 @subsection Composite Sexp Widgets
 @cindex composite sexp widgets
 
-The syntax for the composite widget is:
+The syntax for the composite widget construct is:
 
 @example
-TYPE ::= (NAME [KEYWORD ARGUMENT]...  COMPONENT...)
address@hidden ::= (@var{construct} address@hidden @var{argument}]...  
@var{component}...)
 @end example
 
 @noindent
@@ -1342,19 +1342,43 @@
 will be displayed in the buffer, and will be editable by the user.
 
 @deffn Widget cons
-The value of a @code{cons} widget is a cons-cell where the @sc{car} is
-the value of the first component and the @sc{cdr} is the value of the
-second component.  There must be exactly two components.
+The value of a @code{cons} widget must be a cons-cell whose @sc{car} 
+and @sc{cdr} have two specified types.  It uses this syntax:
+
address@hidden
address@hidden ::= (cons address@hidden @var{argument}]...  @var{car-type} 
@var{cdr-type})
address@hidden example
address@hidden deffn
+
address@hidden Widget choice
+The @code{choice} widget specifies a set of values that match any one
+of a fixed set of types.  Its syntax is as follows:
+
address@hidden
address@hidden ::= (choice address@hidden @var{argument}]...  @var{type} ... )
address@hidden example
+
+The value of a @code{choice} widget can be anything that matches any of the
address@hidden
 @end deffn
 
 @deffn Widget list
-The value of a @code{list} widget is a list containing the value of
-each of its components.
+The value of a @code{list} widget must be a list whose element types
+match the specified component types:
+
address@hidden
address@hidden ::= (list address@hidden @var{argument}]...  
@var{component-type}...)
address@hidden example
+
+Thus, @code{(list string number)} matches lists of two elements,
+the first being a string and the second being a number.
 @end deffn
 
 @deffn Widget vector
-The value of a @code{vector} widget is a vector containing the value of
-each of its component.
+The @code{vector} widget is like the @code{list} widget but matches
+vectors instead of lists.  Thus, @code{(vector string number)} matches
+vectors of two elements, the first being a string and the second being
+a number.
 @end deffn
 
 The above suffice for specifying fixed size lists and vectors.  To get
@@ -1363,7 +1387,7 @@
 keyword.  If any component of a composite widget has the @code{:inline}
 keyword set, its value must be a list which will then be spliced into
 the composite.  For example, to specify a list whose first element must
-be a file name, and whose remaining arguments should either be the
+be a file name, and whose remaining elements should either be the
 symbol @code{t} or two files, you can use the following widget
 specification:
 
@@ -1376,29 +1400,32 @@
 @end example
 
 The value of a widget of this type will either have the form
address@hidden(file t)} or @code{(file string string)}.
address@hidden(file t)} or @code{(file @var{string} @var{string})}.
 
-This concept of inline is probably hard to understand.  It was certainly
-hard to implement, so instead of confusing you more by trying to explain
-it here, I'll just suggest you meditate over it for a while.
-
address@hidden Widget choice
-Allows you to edit a sexp which may have one of a fixed set of types.
-It is currently implemented with the @code{choice-menu} basic widget,
-and has a similar syntax.
address@hidden deffn
+This concept of @code{:inline} may be hard to understand.  It was
+certainly hard to implement, so instead of confusing you more by
+trying to explain it here, I'll just suggest you meditate over it for
+a while.
 
 @deffn Widget set
-Allows you to specify a type which must be a list whose elements all
-belong to the given set.  The elements of the list are not significant.
-This is implemented on top of the @code{checklist} basic widget, and has
-a similar syntax.
+Specifies a type whose values are the lists whose elements all belong
+to a given set.  The order of elements of the list is not significant.
+Here's the syntax:
+
address@hidden
address@hidden ::= (set address@hidden @var{argument}]...  
@var{permitted-element} ... )
address@hidden example
+
+Use @code{const} to specify each permitted element, like this:
address@hidden(set (const a) (const b))}.
 @end deffn
 
 @deffn Widget repeat
-Allows you to specify a variable length list whose members are all of
-the same type.  Implemented on top of the @code{editable-list} basic
-widget, and has a similar syntax.
+Specifies a list of any number of elements that fit a certain type.
+
address@hidden
address@hidden ::= (repeat address@hidden @var{argument}]...  @var{type})
address@hidden example
 @end deffn
 
 @node Widget Properties, Defining New Widgets, Sexp Types, Top