X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/4c2ca4f329e16fca4bd3b23c22b45130a29a4ee6..5c3cb846d4e43b7a31f8c4485af9996c7da9fa2c:/man/widget.texi

diff --git a/man/widget.texi b/man/widget.texi
index 171087cd45..f5f366efed 100644
--- a/man/widget.texi
+++ b/man/widget.texi
@@ -3,12 +3,38 @@
 @c %**start of header
 @setfilename ../info/widget
 @settitle The Emacs Widget Library
+@ifnottex
+Copyright @copyright{} 2000 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
+``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+This document is part of a collection distributed under the GNU Free
+Documentation License.  If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software.  Copies published by the Free
+Software Foundation raise funds for GNU development.''
+@end ifnottex
+
 @iftex
 @afourpaper
 @headings double
 @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,20 +58,22 @@
 * Widget Minor Mode::           
 * Utilities::                   
 * Widget Wishlist::             
+* Index::
 @end menu
 
 @node  Introduction, User Interface, Top, Top
 @comment  node-name,  next,  previous,  up
 @section Introduction
 
-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
-hand, Emacs does provide the necessary primitives to implement many
-other widgets within a text buffer.  The @code{widget} package
-simplifies this task.
+Most graphical user interface toolkits 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
+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 +96,7 @@ visible in the buffer.
 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 +107,7 @@ Create an editable list.  The user can insert or delete items in the
 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,38 +116,40 @@ between the fields.  Examples of forms in Emacs are the @file{forms}
 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
-@code{widget-define}, and autoload the function @code{widget-create}. 
+@code{define-widget}, and autoload the function @code{widget-create}. 
 @item wid-edit.el
 Everything else is here, there is no reason to load it explicitly, as
 it will be autoloaded when needed.
@@ -130,10 +160,10 @@ it will be autoloaded when needed.
 @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 +199,9 @@ Select one:
 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 +224,8 @@ Face used for other editing fields.
 
 @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,7 +239,8 @@ If point is not located on a button, invoke the binding in
 @code{widget-global-map} (by default the global map).
 @end deffn
 
-@item mouse-2
+@kindex Mouse-2 @r{(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
 pointer is located in an editable text field, invoke the binding in
@@ -219,32 +252,34 @@ There are several different kind of buttons, all of which are present in
 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 +289,8 @@ Face used for buttons.
 @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 +313,8 @@ Move point @var{count} buttons or editing fields backward.
 @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}).
 
@@ -320,7 +358,8 @@ Interface}).
 					     '("En" "To" "Tre"))
 			   (widget-setup))
 		 "other work")
-  (widget-insert " for more information.\n\nNumbers: count to three below\n")
+  (widget-insert 
+    " for more information.\n\nNumbers: count to three below\n")
   (setq widget-example-repeat
 	(widget-create 'editable-list
 		       :entry-format "%i %d %v"
@@ -389,7 +428,7 @@ Delete @var{widget} and remove it from the buffer.
 @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 +440,19 @@ recommended way to do that is with @code{widget-insert}.
 
 @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}
+@code{widget-backward}, respectively.  @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 +475,15 @@ Where, @var{name} is a widget name, @var{keyword} is the name of a
 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 +533,14 @@ representation of the value if there is no tag.
 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 +555,45 @@ The string is inserted literally.
 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}.
+Specifies how to display a message whenever you move to the widget with
+either @code{widget-forward} or @code{widget-backward} or move the mouse
+over it (using the standard @code{help-echo} mechanism).  The argument
+is either a string to display or a function of one argument, the widget,
+which should return a string to display.
 
+@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 +601,29 @@ is the widget itself, the second argument is the widget that was
 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 +631,7 @@ The following predefined function can be used:
 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 +651,12 @@ When on a widget with no tabbing order specified, go to the next widget
 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
+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 +668,7 @@ arguments, which will be used when creating the @code{radio-button} or
 @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 +697,7 @@ If non-nil, allow glyphs to appear on displays where they are supported.
 @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 +722,7 @@ String to suffix links.
 @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 +730,14 @@ Syntax:
 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 +745,13 @@ Syntax:
 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 +760,7 @@ TYPE ::= (push-button [KEYWORD ARGUMENT]...  [ VALUE ])
 @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 +776,7 @@ String to suffix push buttons.
 @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 +788,55 @@ The @var{value}, if present, is used to initialize the @code{:value}
 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{?*}
+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 +850,26 @@ match any value matching at least one of the specified @var{type}
 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 +877,7 @@ The list of types.
 @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 +893,37 @@ arguments.
 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.
+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 +933,8 @@ widget after it has been created with the function
 @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 +944,7 @@ you call @code{widget-delete}.
 @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 +959,7 @@ buffer.  This widget will only match the specified value.
 @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 +976,7 @@ the specified value.
 @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 +984,35 @@ Syntax:
 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 +1023,7 @@ TYPE ::= (checkbox [KEYWORD ARGUMENT]...)
 @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 +1031,15 @@ Syntax:
 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,23 +1052,28 @@ Replace with the checkbox.
 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
 non-nil, it will allow the items to come in any sequence.  However, if
 you extract the value they will be in the sequence given in the
-checklist.  I.e. the original sequence is forgotten.
+checklist, i.e.@: the original sequence is forgotten.
 
-@item button-args
+@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.
+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 +1081,7 @@ The list of types.
 @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 +1092,10 @@ TYPE ::= (editable-list [KEYWORD ARGUMENT]... TYPE)
 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 +1111,37 @@ Insert the @b{[DEL]} button.
 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 +1154,11 @@ The value is a list, with one member for each @var{type}.
 @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 +1169,14 @@ available.  These basically fall in the following categories.
 
 @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 +1206,13 @@ An immutable symbol that is bound as a function.
 
 @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 +1223,20 @@ This will allow you to edit any valid s-expression in an editable buffer
 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 +1244,10 @@ TYPE ::= (NAME [KEYWORD ARGUMENT]...  [ VALUE ])
 
 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 +1268,7 @@ completion.
 
 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 +1308,23 @@ either nil meaning false, or non-nil meaning true.
 
 @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 +1339,7 @@ each of its component.
 
 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 +1356,10 @@ specification:
 @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 +1370,22 @@ and has a similar syntax.
 
 @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}.
@@ -1303,12 +1428,16 @@ Non-nil if @var{widget} has a value (even nil) for property @var{property}.
 @end defun
 
 Occasionally it can be useful to know which kind of widget you have,
-i.e. the name of the widget type you gave when the widget was created. 
+i.e.@: the name of the widget type you gave when the widget was created. 
 
 @defun widget-type widget
 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,13 +1478,15 @@ its ancestors have been deactivated.  Do not attempt to set the
 @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 to create a shorthand for more complex widgets, including specifying
 component widgets and new default values for the keyword
 arguments. 
 
-@defun widget-define name class doc &rest args
+@defun define-widget name class doc &rest args
 Define a new widget type named @var{name} from @code{class}.
 
 @var{name} and class should both be symbols, @code{class} should be one
@@ -1380,16 +1511,17 @@ create identical widgets:
 
 @end defun
 
-Using @code{widget-define} just stores the definition of the widget type
+Using @code{define-widget} just stores the definition of the widget type
 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 +1538,7 @@ Convert @code{:args} as widget types in @var{widget}.
 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 +1546,32 @@ internal 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 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 +1584,7 @@ The following predefined function can be used here:
 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 +1595,19 @@ The following predefined function can be used here:
 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 +1619,7 @@ Tell @code{:parent} of @var{widget} to handle the @code{:action}.
 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 +1643,12 @@ default'' in this text.
 @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 +1668,10 @@ When called interactively, use the position of point.
 @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 +1686,7 @@ Keymap used in @code{widget-minor-mode}.
 @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 +1695,14 @@ non-nil.@refill
 @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 +1711,7 @@ and @kbd{C-o} (suggested by @sc{rms}).
 
 @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,10 +1755,17 @@ See @code{TeX-printer-list} for an explanation.
 @kbd{C-h} in @code{widget-prompt-value} should give type specific help.
 
 @item 
-A mailto widget.
-
+Add a @code{mailto} widget.
 @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
 @bye