Mercurial > emacs

changeset 30775:33d2bde9a99a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
(Top): Add Index in the menu. (many nodes): Add index entries. (Index): New node.
author Eli Zaretskii <eliz@gnu.org>
date Sun, 13 Aug 2000 18:28:04 +0000
parents aa8e1dfb2873
children ec759fa10ad9
files man/widget.texi
diffstat 1 files changed, 248 insertions(+), 118 deletions(-) [+]
line wrap: on
line diff
--- a/man/widget.texi	Sun Aug 13 09:09:02 2000 +0000
+++ b/man/widget.texi	Sun Aug 13 18:28:04 2000 +0000
@@ -9,6 +9,10 @@
 @end iftex
 @c %**end of header
 
+@syncodeindex fn cp
+@syncodeindex vr cp
+@syncodeindex ky cp
+
 @dircategory Emacs
 @direntry
 * Widget: (widget).      Documenting the "widget" package used by the
@@ -32,6 +36,7 @@
 * Widget Minor Mode::           
 * Utilities::                   
 * Widget Wishlist::             
+* Index::
 @end menu
 
 @node  Introduction, User Interface, Top, Top
@@ -41,11 +46,13 @@
 Most graphical user interface toolkits, such as Motif and XView, provide
 a number of standard user interface controls (sometimes known as
 `widgets' or `gadgets').  Emacs doesn't really support anything like
-this, except for an incredible powerful text ``widget''.  On the other
+this, except for an incredibly powerful text ``widget''.  On the other
 hand, Emacs does provide the necessary primitives to implement many
 other widgets within a text buffer.  The @code{widget} package
 simplifies this task.
 
+@cindex basic widgets
+@cindex widgets, basic types
 The basic widgets are:
 
 @table @code
@@ -68,7 +75,7 @@
 A simple constant widget intended to be used in the @code{menu-choice} and
 @code{radio-button-choice} widgets. 
 @item choice-item
-An button item only intended for use in choices.  When invoked, the user
+A button item only intended for use in choices.  When invoked, the user
 will be asked to select another option from the choice widget.
 @item toggle
 A simple @samp{on}/@samp{off} switch.
@@ -79,7 +86,7 @@
 list.  Each list item is itself a widget.
 @end table
 
-Now of what possible use can support for widgets be in a text editor?
+Now, of what possible use can support for widgets be in a text editor?
 I'm glad you asked.  The answer is that widgets are useful for
 implementing forms.  A @dfn{form} in Emacs is a buffer where the user is
 supposed to fill out a number of fields, each of which has a specific
@@ -88,34 +95,36 @@
 package (of course), the customize buffers, the mail and news compose
 modes, and the @sc{html} form support in the @file{w3} browser.  
 
+@cindex widget library, why use it
 The advantages for a programmer of using the @code{widget} package to
 implement forms are:
 
 @enumerate
 @item
-More complex field than just editable text are supported. 
+More complex fields than just editable text are supported. 
 @item
-You can give the user immediate feedback if he enters invalid data in a
+You can give the users immediate feedback if they enter invalid data in a
 text field, and sometimes prevent entering invalid data.
 @item 
-You can have fixed sized fields, thus allowing multiple field to be
+You can have fixed sized fields, thus allowing multiple fields to be
 lined up in columns.
 @item
 It is simple to query or set the value of a field. 
 @item 
-Editing happens in buffer, not in the mini-buffer.
+Editing happens in the buffer, not in the mini-buffer.
 @item 
 Packages using the library get a uniform look, making them easier for
 the user to learn.
 @item 
-As support for embedded graphics improve, the widget library will
-extended to support it.  This means that your code using the widget
-library will also use the new graphic features by automatic.
+As support for embedded graphics improve, the widget library will be
+extended to use the GUI features.  This means that your code using the
+widget library will also use the new graphic features automatically.
 @end enumerate
 
 In order to minimize the code that is loaded by users who does not
 create any widgets, the code has been split in two files:
 
+@cindex widget library, files
 @table @file
 @item widget.el
 This will declare the user variables, define the function
@@ -130,10 +139,10 @@
 @section User Interface
 
 A form consist of read only text for documentation and some fields,
-where each the fields contain two parts, as tag and a value.  The tags
-are used to identify the fields, so the documentation can refer to the
-foo field, meaning the field tagged with @samp{Foo}. Here is an example
-form:
+where each field contains two parts, a tag and a value.  The tags are
+used to identify the fields, so the documentation can refer to the
+@samp{foo field}, meaning the field tagged with @samp{Foo}. Here is an
+example form:
 
 @example
 Here is some documentation.
@@ -169,9 +178,9 @@
 The top level widgets in is example are tagged @samp{Name},
 @samp{Choose}, @samp{Address}, @samp{_other work_}, @samp{Numbers},
 @samp{Select multiple}, @samp{Select one}, @samp{[Apply Form]}, and
-@samp{[Reset Form]}.  There are basically two thing the user can do within
-a form, namely editing the editable text fields and activating the
-buttons.
+@samp{[Reset Form]}.  There are basically two things the user can do
+within a form, namely editing the editable text fields and activating
+the buttons.
 
 @subsection Editable Text Fields
 
@@ -194,6 +203,8 @@
 
 @subsection Buttons
 
+@cindex widget buttons
+@cindex button widgets
 Some portions of the buffer have an associated @dfn{action}, which can
 be @dfn{invoked} by a standard key or mouse command.  These portions
 are called @dfn{buttons}.  The default commands for activating a button
@@ -207,6 +218,7 @@
 @code{widget-global-map} (by default the global map).
 @end deffn
 
+@kindex mouse-2, on button widgets
 @item mouse-2
 @deffn Command widget-button-click @var{event}
 Invoke the button at the location of the mouse pointer.  If the mouse
@@ -219,32 +231,34 @@
 the example:
 
 @table @emph
-@item The Option Field Tags.
+@cindex option field tag
+@item The Option Field Tags
 When you invoke one of these buttons, you will be asked to choose
 between a number of different options.  This is how you edit an option
 field.  Option fields are created by the @code{menu-choice} widget.  In
 the example, @samp{@b{Choose}} is an option field tag.
-@item The @samp{@b{[INS]}} and @samp{@b{[DEL]}} buttons.
-Activating these will insert or delete elements from a editable list.
+@item The @samp{@b{[INS]}} and @samp{@b{[DEL]}} buttons
+Activating these will insert or delete elements from an editable list.
 The list is created by the @code{editable-list} widget. 
-@item Embedded Buttons.
+@cindex embedded buttons
+@item Embedded Buttons
 The @samp{@b{_other work_}} is an example of an embedded
-button. Embedded buttons are not associated with a fields, but can serve
+button.  Embedded buttons are not associated with a fields, but can serve
 any purpose, such as implementing hypertext references.  They are
 usually created by the @code{link} widget.
-@item The @samp{@b{[ ]}} and @samp{@b{[X]}} buttons.
+@item The @samp{@b{[ ]}} and @samp{@b{[X]}} buttons
 Activating one of these will convert it to the other.  This is useful
-for implementing multiple-choice fields.  You can create it wit
-@item The @samp{@b{( )}} and @samp{@b{(*)}} buttons.
+for implementing multiple-choice fields.  You can create it with the
+@code{checkbox} widget.
+@item The @samp{@b{( )}} and @samp{@b{(*)}} buttons
 Only one radio button in a @code{radio-button-choice} widget can be
 selected at any time.  When you invoke one of the unselected radio
 buttons, it will be selected and the previous selected radio button will
 become unselected.
-@item The @samp{@b{[Apply Form]}} @samp{@b{[Reset Form]}} buttons.
-These are explicit buttons made with the @code{push-button} widget.  The main
-difference from the @code{link} widget is that the buttons are will be
+@item The @samp{@b{[Apply Form]}} @samp{@b{[Reset Form]}} buttons
+These are explicit buttons made with the @code{push-button} widget.  The
+main difference from the @code{link} widget is that the buttons will be
 displayed as GUI buttons when possible.
-enough. 
 @end table
 
 To make them easier to locate, buttons are emphasized in the buffer.  
@@ -254,7 +268,8 @@
 @end deffn
 
 @defopt widget-mouse-face
-Face used for buttons when the mouse pointer is above it.
+Face used for highlighting a button when the mouse pointer moves across
+it.
 @end defopt
 
 @subsection Navigation
@@ -277,6 +292,8 @@
 @comment  node-name,  next,  previous,  up
 @section Programming Example
 
+@cindex widgets, programming example
+@cindex example of using widgets
 Here is the code to implement the user interface example (@pxref{User
 Interface}).
 
@@ -389,7 +406,7 @@
 @end defun
 
 @defun widget-setup 
-Setup a buffer to support widgets. 
+Set up a buffer to support widgets. 
 
 This should be called after creating all the widgets and before allowing
 the user to edit them.
@@ -401,17 +418,19 @@
 
 @defun widget-insert 
 Insert the arguments, either strings or characters, at point.
-The inserted text will be read only.
+The inserted text will be read-only.
 @end defun
 
 There is a standard widget keymap which you might find useful.
 
+@findex widget-button-press
+@findex widget-button-click
 @defvr Const widget-keymap
 A keymap with the global keymap as its parent.@*
 @key{TAB} and @kbd{C-@key{TAB}} are bound to @code{widget-forward} and
 @code{widget-backward}, respectively.  @kbd{@key{RET}} and @kbd{mouse-2}
 are bound to @code{widget-button-press} and
-@code{widget-button-}.@refill
+@code{widget-button-click}.@refill
 @end defvr
 
 @defvar widget-global-map
@@ -434,12 +453,15 @@
 property, @var{argument} is the value of the property, and @var{args}
 are interpreted in a widget specific way.
 
-There following keyword arguments that apply to all widgets:
+@cindex keyword arguments
+The following keyword arguments that apply to all widgets:
 
 @table @code
+@vindex value@r{ keyword}
 @item :value
 The initial value for widgets of this type.
 
+@vindex format@r{ keyword}
 @item :format
 This string will be inserted in the buffer when you create a widget.
 The following @samp{%} escapes are available:
@@ -489,12 +511,14 @@
 Insert a literal @samp{%}. 
 @end table
 
+@vindex button-face@r{ keyword}
 @item :button-face
 Face used to highlight text inside %[ %] in the format.
 
+@vindex button-prefix@r{ keyword}
+@vindex button-suffix@r{ keyword}
 @item :button-prefix
 @itemx :button-suffix
-
 Text around %[ %] in the format.
 
 These can be
@@ -509,34 +533,42 @@
 The value of the symbol is expanded according to this table.
 @end table
 
+@vindex doc@r{ keyword}
 @item :doc
 The string inserted by the @samp{%d} escape in the format
 string.  
 
+@vindex tag@r{ keyword}
 @item :tag
 The string inserted by the @samp{%t} escape in the format
 string.  
 
+@vindex tag-glyph@r{ keyword}
 @item :tag-glyph
-Name of image to use instead of the string specified by `:tag' on
+Name of image to use instead of the string specified by @code{:tag} on
 Emacsen that supports it.
 
+@vindex help-echo@r{ keyword}
 @item :help-echo
 Message displayed whenever you move to the widget with either
 @code{widget-forward} or @code{widget-backward}.
 
+@vindex indent@r{ keyword}
 @item :indent
 An integer indicating the absolute number of spaces to indent children
 of this widget.
 
+@vindex offset@r{ keyword}
 @item :offset
 An integer indicating how many extra spaces to add to the widget's
 grandchildren compared to this widget.
 
+@vindex extra-offset@r{ keyword}
 @item :extra-offset
 An integer indicating how many extra spaces to add to the widget's
 children compared to this widget.
 
+@vindex notify@r{ keyword}
 @item :notify
 A function called each time the widget or a nested widget is changed.
 The function is called with two or three arguments.  The first argument
@@ -544,25 +576,29 @@
 changed, and the third argument is the event leading to the change, if
 any. 
 
+@vindex menu-tag@r{ keyword}
 @item :menu-tag
 Tag used in the menu when the widget is used as an option in a
 @code{menu-choice} widget.
 
+@vindex menu-tag-get@r{ keyword}
 @item :menu-tag-get
 Function used for finding the tag when the widget is used as an option
 in a @code{menu-choice} widget.  By default, the tag used will be either the
 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
 representation of the @code{:value} property if not.
 
+@vindex match@r{ keyword}
 @item :match
 Should be a function called with two arguments, the widget and a value,
 and returning non-nil if the widget can represent the specified value.
 
+@vindex validate@r{ keyword}
 @item :validate
-A function which takes a widget as an argument, and return nil if the
-widget's current value is valid for the widget.  Otherwise it should
-return the widget containing the invalid data, and set that widget's
-@code{:error} property to a string explaining the error.
+A function which takes a widget as an argument, and returns @code{nil}
+if the widget's current value is valid for the widget.  Otherwise it
+should return the widget containing the invalid data, and set that
+widget's @code{:error} property to a string explaining the error.
 
 The following predefined function can be used:
 
@@ -570,6 +606,7 @@
 All the @code{:children} of @var{widget} must be valid.
 @end defun
 
+@vindex tab-order@r{ keyword}
 @item :tab-order
 Specify the order in which widgets are traversed with
 @code{widget-forward} or @code{widget-backward}.  This is only partially
@@ -589,10 +626,12 @@
 in the buffer with a positive tabbing order, or @code{nil}
 @end enumerate
 
+@vindex parent@r{ keyword}
 @item :parent
 The parent of a nested widget (e.g. a @code{menu-choice} item or an
 element of a @code{editable-list} widget).
 
+@vindex sibling-args@r{ keyword}
 @item :sibling-args
 This keyword is only used for members of a @code{radio-button-choice} or
 @code{checklist}.  The value should be a list of extra keyword
@@ -604,7 +643,7 @@
 @deffn {User Option} widget-glyph-directory
 Directory where glyphs are found.  
 Widget will look here for a file with the same name as specified for the
-image, with either a @samp{.xpm} (if supported) or @samp{.xbm} extension.
+image, with either a @file{.xpm} (if supported) or @file{.xbm} extension.
 @end deffn
 
 @deffn{User Option} widget-glyph-enable
@@ -633,6 +672,7 @@
 @node link, url-link, Basic Types, Basic Types
 @comment  node-name,  next,  previous,  up
 @subsection The @code{link} Widget
+@findex link@r{ widget}
 
 Syntax:
 
@@ -657,6 +697,7 @@
 @node url-link, info-link, link, Basic Types
 @comment  node-name,  next,  previous,  up
 @subsection The @code{url-link} Widget
+@findex url-link@r{ widget}
 
 Syntax:
 
@@ -664,12 +705,14 @@
 TYPE ::= (url-link [KEYWORD ARGUMENT]...  URL)
 @end example
 
+@findex browse-url-browser-function@r{, and @code{url-link} widget}
 When this link is invoked, the @sc{www} browser specified by
 @code{browse-url-browser-function} will be called with @var{url}. 
 
 @node info-link, push-button, url-link, Basic Types
 @comment  node-name,  next,  previous,  up
 @subsection The @code{info-link} Widget
+@findex info-link@r{ widget}
 
 Syntax:
 
@@ -677,12 +720,13 @@
 TYPE ::= (info-link [KEYWORD ARGUMENT]...  ADDRESS)
 @end example
 
-When this link is invoked, the built-in info browser is started on
+When this link is invoked, the built-in Info reader is started on
 @var{address}. 
 
 @node  push-button, editable-field, info-link, Basic Types
 @comment  node-name,  next,  previous,  up
 @subsection The @code{push-button} Widget
+@findex push-button@r{ widget}
 
 Syntax:
 
@@ -691,7 +735,7 @@
 @end example
 
 The @var{value}, if present, is used to initialize the @code{:value}
-property. The value should be a string, which will be inserted in the
+property.  The value should be a string, which will be inserted in the
 buffer. 
 
 By default the tag will be shown in brackets.
@@ -707,6 +751,7 @@
 @node editable-field, text, push-button, Basic Types
 @comment  node-name,  next,  previous,  up
 @subsection The @code{editable-field} Widget
+@findex editable-field@r{ widget}
 
 Syntax:
 
@@ -718,45 +763,55 @@
 property.  The value should be a string, which will be inserted in
 field.  This widget will match all string values.
 
-The following extra properties are recognized.
+The following extra properties are recognized:
 
 @table @code
+@vindex size@r{ keyword}
 @item :size
 The width of the editable field.@*
 By default the field will reach to the end of the line.
 
+@vindex value-face@r{ keyword}
 @item :value-face
 Face used for highlighting the editable field.  Default is
-@code{widget-field-face}. 
+@code{widget-field-face}, see @ref{User Interface}. 
 
+@vindex secret@r{ keyword}
 @item :secret
 Character used to display the value.  You can set this to e.g. @code{?*}
 if the field contains a password or other secret information.  By
-default, the value is not secret.
+default, this is nil, and the value is not secret.
 
+@vindex valid-regexp@r{ keyword}
 @item :valid-regexp
 By default the @code{:validate} function will match the content of the
 field with the value of this attribute.  The default value is @code{""}
 which matches everything.
 
+@vindex keymap@r{ keyword}
+@vindex widget-field-keymap
 @item :keymap
 Keymap used in the editable field.  The default value is
 @code{widget-field-keymap}, which allows you to use all the normal
-editing commands, even if the buffers major mode suppress some of them.
-Pressing return invokes the function specified by @code{:action}. 
+editing commands, even if the buffer's major mode suppresses some of
+them.  Pressing @key{RET} invokes the function specified by
+@code{:action}.
 @end table
 
 @node text, menu-choice, editable-field, Basic Types
 @comment  node-name,  next,  previous,  up
 @subsection The @code{text} Widget
+@findex text@r{ widget}
 
+@vindex widget-text-keymap
 This is just like @code{editable-field}, but intended for multiline text
 fields.  The default @code{:keymap} is @code{widget-text-keymap}, which
-does not rebind the return key.
+does not rebind the @key{RET} key.
 
 @node menu-choice, radio-button-choice, text, Basic Types
 @comment  node-name,  next,  previous,  up
 @subsection The @code{menu-choice} Widget
+@findex menu-choice@r{ widget}
 
 Syntax:
 
@@ -770,21 +825,26 @@
 arguments.
 
 @table @code
+@vindex void@r{ keyword}
 @item :void 
 Widget type used as a fallback when the value does not match any of the
 specified @var{type} arguments.
 
+@vindex case-fold@r{ keyword}
 @item :case-fold
 Set this to nil if you don't want to ignore case when prompting for a
 choice through the minibuffer.
 
+@vindex children@r{ keyword}
 @item :children
-A list whose car is the widget representing the currently chosen type in
-the buffer. 
+A list whose @code{car} is the widget representing the currently chosen
+type in the buffer.
 
+@vindex choice@r{ keyword}
 @item :choice
-The current chosen type
+The current chosen type.
 
+@vindex args@r{ keyword}
 @item :args 
 The list of types. 
 @end table
@@ -792,6 +852,7 @@
 @node radio-button-choice, item, menu-choice, Basic Types
 @comment  node-name,  next,  previous,  up
 @subsection The @code{radio-button-choice} Widget
+@findex radio-button-choice@r{ widget}
 
 Syntax:
 
@@ -807,31 +868,37 @@
 The following extra properties are recognized.
 
 @table @code
+@vindex entry-format@r{ keyword}
 @item :entry-format
 This string will be inserted for each entry in the list.
 The following @samp{%} escapes are available:
 @table @samp
 @item %v
-Replaced with the buffer representation of the @var{type} widget.
+Replace with the buffer representation of the @var{type} widget.
 @item %b
 Replace with the radio button.
 @item %%
 Insert a literal @samp{%}. 
 @end table
 
-@item button-args
+@vindex button-args@r{ keyword}
+@item :button-args
 A list of keywords to pass to the radio buttons.  Useful for setting
 e.g. the @samp{:help-echo} for each button.
 
+@vindex buttons@r{ keyword}
 @item :buttons
 The widgets representing the radio buttons.
 
+@vindex children@r{ keyword}
 @item :children
 The widgets representing each type.
 
+@vindex choice@r{ keyword}
 @item :choice
 The current chosen type
 
+@vindex args@r{ keyword}
 @item :args 
 The list of types. 
 @end table
@@ -841,8 +908,8 @@
 @code{widget-radio-add-item}. 
 
 @defun widget-radio-add-item widget type
-Add to @code{radio-button-choice} widget @var{widget} a new radio button item of type
-@var{type}. 
+Add to @code{radio-button-choice} widget @var{widget} a new radio button
+item of type @var{type}.
 @end defun
 
 Please note that such items added after the @code{radio-button-choice}
@@ -852,6 +919,7 @@
 @node item, choice-item, radio-button-choice, Basic Types
 @comment  node-name,  next,  previous,  up
 @subsection The @code{item} Widget
+@findex item@r{ widget}
 
 Syntax:
 
@@ -866,6 +934,7 @@
 @node choice-item, toggle, item, Basic Types
 @comment  node-name,  next,  previous,  up
 @subsection The @code{choice-item} Widget
+@findex choice-item@r{ widget}
 
 Syntax:
 
@@ -882,6 +951,7 @@
 @node toggle, checkbox, choice-item, Basic Types
 @comment  node-name,  next,  previous,  up
 @subsection The @code{toggle} Widget
+@findex toggle@r{ widget}
 
 Syntax:
 
@@ -889,30 +959,35 @@
 TYPE ::= (toggle [KEYWORD ARGUMENT]...)
 @end example
 
-The widget has two possible states, `on' and `off', which correspond to
-a @code{t} or @code{nil} value respectively.
+The widget has two possible states, @samp{on} and @samp{off}, which
+correspond to a @code{t} or @code{nil} value, respectively.
 
-The following extra properties are recognized.
+The following extra properties are recognized:
 
 @table @code
 @item :on
-String representing the `on' state.  By default the string @samp{on}.
+A string representing the @samp{on} state.  By default the string
+@samp{on}.
 @item :off 
-String representing the `off' state.  By default the string @samp{off}.
+A string representing the @samp{off} state.  By default the string
+@samp{off}.
+@vindex on-glyph@r{ keyword}
 @item :on-glyph
-Name of a glyph to be used instead of the `:on' text string, on emacsen
-that supports it.
+Name of a glyph to be used instead of the @samp{:on} text string, on
+emacsen that supports this.
+@vindex off-glyph@r{ keyword}
 @item :off-glyph
-Name of a glyph to be used instead of the `:off' text string, on emacsen
-that supports it.
+Name of a glyph to be used instead of the @samp{:off} text string, on
+emacsen that supports this.
 @end table
 
 @node checkbox, checklist, toggle, Basic Types
 @comment  node-name,  next,  previous,  up
 @subsection The @code{checkbox} Widget
+@findex checkbox@r{ widget}
 
-The widget has two possible states, `selected' and `unselected', which
-corresponds to a @code{t} or @code{nil} value.
+This widget has two possible states, @samp{selected} and
+@samp{unselected}, which corresponds to a @code{t} or @code{nil} value.
 
 Syntax:
 
@@ -923,6 +998,7 @@
 @node checklist, editable-list, checkbox, Basic Types
 @comment  node-name,  next,  previous,  up
 @subsection The @code{checklist} Widget
+@findex checklist@r{ widget}
 
 Syntax:
 
@@ -930,14 +1006,15 @@
 TYPE ::= (checklist [KEYWORD ARGUMENT]...  TYPE ... )
 @end example
 
-The @var{type} arguments represents each checklist item.  The widget's
-value will be a list containing the values of all ticked @var{type}
+The @var{type} arguments represent each checklist item.  The widget's
+value will be a list containing the values of all checked @var{type}
 arguments.  The checklist widget will match a list whose elements all
 match at least one of the specified @var{type} arguments.
 
-The following extra properties are recognized.
+The following extra properties are recognized:
 
 @table @code
+@vindex entry-format@r{ keyword}
 @item :entry-format
 This string will be inserted for each entry in the list.
 The following @samp{%} escapes are available:
@@ -950,6 +1027,7 @@
 Insert a literal @samp{%}. 
 @end table
 
+@vindex greedy@r{ keyword}
 @item :greedy
 Usually a checklist will only match if the items are in the exact
 sequence given in the specification.  By setting @code{:greedy} to
@@ -957,16 +1035,20 @@
 you extract the value they will be in the sequence given in the
 checklist.  I.e. the original sequence is forgotten.
 
+@vindex button-args@r{ keyword}
 @item button-args
 A list of keywords to pass to the checkboxes.  Useful for setting
 e.g. the @samp{:help-echo} for each checkbox.
 
+@vindex buttons@r{ keyword}
 @item :buttons
 The widgets representing the checkboxes.
 
+@vindex children@r{ keyword}
 @item :children
 The widgets representing each type.
 
+@vindex args@r{ keyword}
 @item :args 
 The list of types. 
 @end table
@@ -974,6 +1056,7 @@
 @node editable-list, group, checklist, Basic Types
 @comment  node-name,  next,  previous,  up
 @subsection The @code{editable-list} Widget
+@findex editable-list@r{ widget}
 
 Syntax:
 
@@ -984,9 +1067,10 @@
 The value is a list, where each member represents one widget of type
 @var{type}. 
 
-The following extra properties are recognized.
+The following extra properties are recognized:
 
 @table @code
+@vindex entry-format@r{ keyword}
 @item :entry-format
 This string will be inserted for each entry in the list.
 The following @samp{%} escapes are available:
@@ -1002,32 +1086,37 @@
 Insert a literal @samp{%}. 
 @end table
 
+@vindex insert-button-args@r{ keyword}
 @item :insert-button-args
 A list of keyword arguments to pass to the insert buttons.
 
+@vindex delete-button-args@r{ keyword}
 @item :delete-button-args
 A list of keyword arguments to pass to the delete buttons.
 
+@vindex append-button-args@r{ keyword}
 @item :append-button-args
 A list of keyword arguments to pass to the trailing insert button.
 
-
+@vindex buttons@r{ keyword}
 @item :buttons
 The widgets representing the insert and delete buttons.
 
+@vindex children@r{ keyword}
 @item :children
 The widgets representing the elements of the list.
 
+@vindex args@r{ keyword}
 @item :args
-List whose car is the type of the list elements.
-
+List whose @code{car} is the type of the list elements.
 @end table
 
 @node group,  , editable-list, Basic Types
 @comment  node-name,  next,  previous,  up
 @subsection The @code{group} Widget
+@findex group@r{ widget}
 
-This widget simply group other widget together.
+This widget simply group other widgets together.
 
 Syntax:
 
@@ -1040,9 +1129,11 @@
 @node Sexp Types, Widget Properties, Basic Types, Top
 @comment
 @section Sexp Types
+@cindex sexp types
 
-A number of widgets for editing s-expressions (lisp types) are also
-available.  These basically fall in the following categories.
+A number of widgets for editing @dfn{s-expressions} (lisp types), sexp
+for short, are also available.  These basically fall in several
+categories described in this section.
 
 @menu
 * constants::                   
@@ -1053,13 +1144,14 @@
 
 @node constants, generic, Sexp Types, Sexp Types
 @comment  node-name,  next,  previous,  up
-@subsection The Constant Widgets.
+@subsection The Constant Widgets
+@cindex constant widgets
 
 The @code{const} widget can contain any lisp expression, but the user is
-prohibited from editing edit it, which is mainly useful as a component
-of one of the composite widgets.
+prohibited from editing it, which is mainly useful as a component of one
+of the composite widgets.
 
-The syntax for the @code{const} widget is
+The syntax for the @code{const} widget is:
 
 @example
 TYPE ::= (const [KEYWORD ARGUMENT]...  [ VALUE ])
@@ -1089,12 +1181,13 @@
 
 @node generic, atoms, constants, Sexp Types
 @comment  node-name,  next,  previous,  up
-@subsection Generic Sexp Widget.
+@subsection Generic Sexp Widget
+@cindex generic sexp widget
 
 The @code{sexp} widget can contain any lisp expression, and allows the
 user to edit it inline in the buffer.
 
-The syntax for the @code{sexp} widget is
+The syntax for the @code{sexp} widget is:
 
 @example
 TYPE ::= (sexp [KEYWORD ARGUMENT]...  [ VALUE ])
@@ -1105,18 +1198,20 @@
 field. 
 
 The @code{sexp} widget takes the same keyword arguments as the
-@code{editable-field} widget.
+@code{editable-field} widget.  @xref{editable-field}.
 @end deffn
 
 @node atoms, composite, generic, Sexp Types
 @comment  node-name,  next,  previous,  up
-@subsection Atomic Sexp Widgets.
+@subsection Atomic Sexp Widgets
+@cindex atomic sexp widget
 
-The atoms are s-expressions that does not consist of other
-s-expressions.  A string is an atom, while a list is a composite type.
-You can edit the value of an atom with the following widgets.  
+The atoms are s-expressions that do not consist of other s-expressions.
+For example, a string, a file name, or a symbol are atoms, while a list
+is a composite type.  You can edit the value of an atom with the
+following widgets.
 
-The syntax for all the atoms are
+The syntax for all the atoms are:
 
 @example
 TYPE ::= (NAME [KEYWORD ARGUMENT]...  [ VALUE ])
@@ -1124,10 +1219,10 @@
 
 The @var{value}, if present, is used to initialize the @code{:value}
 property and must be an expression of the same type as the widget.
-I.e. the string widget can only be initialized with a string.
+That is, the string widget can only be initialized with a string.
 
 All the atom widgets take the same keyword arguments as the
-@code{editable-field} widget.
+@code{editable-field} widget.  @xref{editable-field}.
 
 @deffn Widget string
 Allows you to edit a string in an editable field.
@@ -1148,6 +1243,7 @@
 
 Keywords:
 @table @code
+@vindex must-match@r{ keyword}
 @item :must-match
 If this is set to non-nil, only existing file names will be allowed in
 the minibuffer.
@@ -1187,21 +1283,23 @@
 
 @node composite,  , atoms, Sexp Types
 @comment  node-name,  next,  previous,  up
-@subsection Composite Sexp Widgets.
+@subsection Composite Sexp Widgets
+@cindex composite sexp widgets
 
-The syntax for the composite are
+The syntax for the composite widget is:
 
 @example
 TYPE ::= (NAME [KEYWORD ARGUMENT]...  COMPONENT...)
 @end example
 
-Where each @var{component} must be a widget type.  Each component widget
-will be displayed in the buffer, and be editable to the user.
+@noindent
+where each @var{component} must be a widget type.  Each component widget
+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 car is the
-value of the first component and the cdr is the value of the second
-component.  There must be exactly two components. 
+The value of a @code{cons} widget is a cons-cell where the @code{car} is
+the value of the first component and the @code{cdr} is the value of the
+second component.  There must be exactly two components.
 @end deffn
 
 @deffn Widget list
@@ -1216,7 +1314,7 @@
 
 The above suffice for specifying fixed size lists and vectors.  To get
 variable length lists and vectors, you can use a @code{choice},
-@code{set} or @code{repeat} widgets together with the @code{:inline}
+@code{set}, or @code{repeat} widgets together with the @code{:inline}
 keywords.  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
@@ -1233,10 +1331,10 @@
 @end example
 
 The value of a widget of this type will either have the form 
-@samp{(file t)} or @code{(file string string)}.
+@code{(file t)} or @code{(file string 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
+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 choice
@@ -1247,20 +1345,22 @@
 
 @deffn Widget set
 Allows you to specify a type which must be a list whose elements all
-belong to given set.  The elements of the list is not significant.  This
-is implemented on top of the @code{checklist} basic widget, and has a
-similar syntax. 
+belong to 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.
 @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 `editable-list' basic widget,
-and has a similar syntax.
+the same type.  Implemented on top of the @code{editable-list} basic
+widget, and has a similar syntax.
 @end deffn
 
 @node Widget Properties, Defining New Widgets, Sexp Types, Top
 @comment  node-name,  next,  previous,  up
 @section Properties
+@cindex properties of widgets
+@cindex widget properties
 
 You can examine or set the value of a widget by using the widget object
 that was returned by @code{widget-create}.
@@ -1309,6 +1409,10 @@
 Return the name of @var{widget}, a symbol.
 @end defun
 
+@cindex active widget
+@cindex inactive widget
+@cindex activate a widget
+@cindex deactivate a widget
 Widgets can be in two states: active, which means they are modifiable by
 the user, or inactive, which means they cannot be modified by the user.
 You can query or set the state with the following code:
@@ -1349,8 +1453,10 @@
 @node Defining New Widgets, Widget Browser, Widget Properties, Top
 @comment  node-name,  next,  previous,  up
 @section Defining New Widgets
+@cindex new widgets
+@cindex defining new widgets
 
-You can define specialized widgets with @code{define-widget}.  It allows
+You can define specialized widgets with @code{widget-define}.  It allows
 you to create a shorthand for more complex widgets, including specifying
 component widgets and new default values for the keyword
 arguments. 
@@ -1384,12 +1490,13 @@
 in the @code{widget-type} property of @var{name}, which is what
 @code{widget-create} uses.
 
-If you just want to specify defaults for keywords with no complex
+If you only want to specify defaults for keywords with no complex
 conversions, you can use @code{identity} as your conversion function.
 
 The following additional keyword arguments are useful when defining new
 widgets: 
 @table @code
+@vindex convert-widget@r{ keyword}
 @item :convert-widget
 Function to convert a widget type before creating a widget of that
 type.  It takes a widget type as an argument, and returns the converted
@@ -1406,6 +1513,7 @@
 Initialize @code{:value} from @code{:args} in @var{widget}.
 @end defun
 
+@vindex value-to-internal@r{ keyword}
 @item :value-to-internal
 Function to convert the value to the internal format.  The function
 takes two arguments, a widget and an external value, and returns the
@@ -1413,27 +1521,32 @@
 when the widget is created, and on any value set later with
 @code{widget-value-set}.
 
+@vindex value-to-external@r{ keyword}
 @item :value-to-external
 Function to convert the value to the external format.  The function
 takes two arguments, a widget and an internal value, and returns the
-internal value.  The function is called on the present @code{:value}
+external value.  The function is called on the present @code{:value}
 when the widget is created, and on any value set later with
 @code{widget-value-set}.
 
+@vindex create@r{ keyword}
 @item :create
 Function to create a widget from scratch.  The function takes one
 argument, a widget type, and creates a widget of that type, inserts it
 in the buffer, and returns a widget object.
 
+@vindex delete@r{ keyword}
 @item :delete
 Function to delete a widget.  The function takes one argument, a widget,
 and should remove all traces of the widget from the buffer.
 
+@vindex value-create@r{ keyword}
 @item :value-create
 Function to expand the @samp{%v} escape in the format string.  It will
 be called with the widget as its argument and should insert a
 representation of the widget's value in the buffer.
 
+@vindex value-delete@r{ keyword}
 @item :value-delete
 Should remove the representation of the widget's value from the buffer.
 It will be called with the widget as its argument.  It doesn't have to
@@ -1446,6 +1559,7 @@
 Delete all @code{:children} and @code{:buttons} in @var{widget}.
 @end defun
 
+@vindex value-get@r{ keyword}
 @item :value-get 
 Function to extract the value of a widget, as it is displayed in the
 buffer. 
@@ -1456,15 +1570,19 @@
 Return the @code{:value} property of @var{widget}.
 @end defun
 
+@vindex format-handler@r{ keyword}
 @item :format-handler
 Function to handle unknown @samp{%} escapes in the format string.  It
-will be called with the widget and the escape character as arguments.
-You can set this to allow your widget to handle non-standard escapes.
+will be called with the widget and the character that follows the
+@samp{%} as arguments.  You can set this to allow your widget to handle
+non-standard escapes.
 
+@findex widget-default-format-handler
 You should end up calling @code{widget-default-format-handler} to handle
 unknown escape sequences, which will handle the @samp{%h} and any future
 escape sequences, as well as give an error for unknown escapes.
 
+@vindex action@r{ keyword}
 @item :action
 Function to handle user initiated events.  By default, @code{:notify}
 the parent. 
@@ -1476,6 +1594,7 @@
 Optional @var{event} is the event that triggered the action.
 @end defun
 
+@vindex prompt-value@r{ keyword}
 @item :prompt-value
 Function to prompt for a value in the minibuffer.  The function should
 take four arguments, @var{widget}, @var{prompt}, @var{value}, and
@@ -1499,11 +1618,12 @@
 @node Widget Browser, Widget Minor Mode, Defining New Widgets, Top
 @comment  node-name,  next,  previous,  up
 @section Widget Browser
+@cindex widget browser
 
 There is a separate package to browse widgets.  This is intended to help
 programmers who want to examine the content of a widget.  The browser
 shows the value of each keyword, but uses links for certain keywords
-such as `:parent', which avoids printing cyclic structures.
+such as @samp{:parent}, which avoids printing cyclic structures.
 
 @deffn Command widget-browse WIDGET
 Create a widget browser for WIDGET.
@@ -1523,9 +1643,10 @@
 @node  Widget Minor Mode, Utilities, Widget Browser, Top
 @comment  node-name,  next,  previous,  up
 @section Widget Minor Mode
+@cindex widget minor mode
 
 There is a minor mode for manipulating widgets in major modes that
-doesn't provide any support for widgets themselves.  This is mostly
+don't provide any support for widgets themselves.  This is mostly
 intended to be useful for programmers doing experiments. 
 
 @deffn Command widget-minor-mode
@@ -1540,6 +1661,7 @@
 @node  Utilities, Widget Wishlist, Widget Minor Mode, Top
 @comment  node-name,  next,  previous,  up
 @section Utilities.
+@cindex utility functions for widgets
 
 @defun widget-prompt-value widget prompt [ value unbound ]
 Prompt for a value matching @var{widget}, using @var{prompt}.
@@ -1548,13 +1670,14 @@
 @end defun
 
 @defun widget-get-sibling widget
-Get the item @var{widget} is assumed to toggle.
+Get the item which @var{widget} is assumed to toggle.
 This is only meaningful for radio buttons or checkboxes in a list.
 @end defun
 
-@node  Widget Wishlist,  , Utilities, Top
+@node  Widget Wishlist,  Index, Utilities, Top
 @comment  node-name,  next,  previous,  up
 @section Wishlist
+@cindex todo
 
 @itemize @bullet
 @item 
@@ -1563,7 +1686,7 @@
 
 @item 
 The @samp{[INS]} and @samp{[DEL]} buttons should be replaced by a single
-dash (@samp{-}).  The dash should be a button that, when invoked, ask
+dash (@samp{-}).  The dash should be a button that, when invoked, asks
 whether you want to add or delete an item (@sc{rms} wanted to git rid of
 the ugly buttons, the dash is my idea).
 
@@ -1607,9 +1730,16 @@
 @kbd{C-h} in @code{widget-prompt-value} should give type specific help.
 
 @item 
-A mailto widget.
+Add a @code{mailto} widget.
+@end itemize
 
-@end itemize
+@node Index, , Widget Wishlist, Top
+@comment  node-name,  next,  previous,  up
+@unnumbered Index
+
+This is an alphabetical listing of all concepts, functions, commands,
+variables, and widgets described in this manual.
+@printindex cp
 
 @setchapternewpage odd
 @contents