--- widget.orig_texi.txt	2023-08-21 11:45:19.141060600 -0500
+++ widget.texi.txt	2023-08-21 11:43:40.847561200 -0500
@@ -5,34 +5,46 @@
   2.2 Buttons
   2.3 Navigation
 3 Programming Example
-4 Setting Up the Buffer
-5 Basic Types
-  5.1 The ‘link’ Widget
-  5.2 The ‘url-link’ Widget
-  5.3 The ‘info-link’ Widget
-  5.4 The ‘push-button’ Widget
-  5.5 The ‘editable-field’ Widget
-  5.6 The ‘text’ Widget
-  5.7 The ‘menu-choice’ Widget
-  5.8 The ‘radio-button-choice’ Widget
-  5.9 The ‘item’ Widget
-  5.10 The ‘choice-item’ Widget
-  5.11 The ‘toggle’ Widget
-  5.12 The ‘checkbox’ Widget
-  5.13 The ‘checklist’ Widget
-  5.14 The ‘editable-list’ Widget
-  5.15 The ‘group’ Widget
-6 Sexp Types
-  6.1 The Constant Widgets
-  6.2 Generic Sexp Widget
-  6.3 Atomic Sexp Widgets
-  6.4 Composite Sexp Widgets
-7 Properties
-8 Defining New Widgets
-9 Widget Browser
-10 Widget Minor Mode
-11 Utilities
-12 Wishlist
+4 Widgets Basics
+5 Setting Up the Buffer
+6 Working with Widgets
+7 Widgets and the Buffer
+8 Widget Gallery
+  8.1 Basic Types
+    8.1.1 The ‘item’ Widget
+    8.1.2 The ‘link’ Widget
+    8.1.3 The ‘url-link’ Widget
+    8.1.4 The ‘info-link’ Widget
+    8.1.5 The ‘function-link’ Widget
+    8.1.6 The ‘variable-link’ Widget
+    8.1.7 The ‘face-link’ Widget
+    8.1.8 The ‘file-link’ Widget
+    8.1.9 The ‘emacs-library-link’ Widget
+    8.1.10 The ‘emacs-commentary-link’ Widget
+    8.1.11 The ‘push-button’ Widget
+    8.1.12 The ‘editable-field’ Widget
+    8.1.13 The ‘text’ Widget
+    8.1.14 The ‘menu-choice’ Widget
+    8.1.15 The ‘radio-button-choice’ Widget
+    8.1.16 The ‘choice-item’ Widget
+    8.1.17 The ‘toggle’ Widget
+    8.1.18 The ‘radio-button-toggle’ Widget
+    8.1.19 The ‘checkbox’ Widget
+    8.1.20 The ‘checklist’ Widget
+    8.1.21 The ‘editable-list’ Widget
+    8.1.22 The ‘group’ Widget
+    8.1.23 The ‘documentation-string’ Widget
+  8.2 Sexp Types
+    8.2.1 The Constant Widgets
+    8.2.2 Generic Sexp Widget
+    8.2.3 Atomic Sexp Widgets
+    8.2.4 Composite Sexp Widgets
+9 Defining New Widgets
+10 Inspecting Widgets
+11 Widget Minor Mode
+12 Utilities
+13 Customization
+14 Wishlist
 Appendix A GNU Free Documentation License
 Index
 The Emacs Widget Library
@@ -57,7 +69,7 @@
 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
+powerful text “widget”.  On the other hand, Emacs does provide the
 necessary primitives to implement many other widgets within a text
 buffer.  The ‘widget’ package simplifies this task.
 
@@ -71,13 +83,14 @@
 ‘editable-field’
      An editable text field.  It can be either variable or fixed length.
 ‘menu-choice’
-     Allows the user to choose one of multiple options from a menu, each
-     option is itself a widget.  Only the selected option will be
+     Allows the user to choose one of multiple options from a menu,
+     where each option is itself a widget.  Only the selected option is
      visible in the buffer.
 ‘radio-button-choice’
      Allows the user to choose one of multiple options by activating
      radio buttons.  The options are implemented as widgets.  All
-     options will be visible in the buffer.
+     options are visible in the buffer, with the selected one marked as
+     chosen.
 ‘item’
      A simple constant widget intended to be used in the ‘menu-choice’
      and ‘radio-button-choice’ widgets.
@@ -174,11 +187,6 @@
 
    Editable text fields are created by the ‘editable-field’ widget.
 
-   *Warning:* In an ‘editable-field’ widget, the editable field must not
-be adjacent to another widget—that won’t work.  You must put some text
-in between.  Either make this text part of the ‘editable-field’ widget
-itself, or insert it with ‘widget-insert’.
-
    The ‘:format’ keyword is useful for generating the necessary text;
 for instance, if you give it a value of ‘"Name: %v "’, the ‘Name: ’ part
 will provide the necessary separating text before the field and the
@@ -186,34 +194,18 @@
 don’t include the ‘:size’ keyword, the field will extend to the end of
 the line, and the terminating newline will provide separation after.
 
-   *Warning:* In an ‘editable-field’ widget, the ‘%v’ escape must be
-preceded by some other text in the ‘:format’ string (if specified).
-
    The editing text fields are highlighted with the ‘widget-field-face’
 face, making them easy to find.
 
- -- Face: widget-field-face
-     Face used for other editing fields.
-
 2.2 Buttons
 ===========
 
 Some portions of the buffer have an associated “action”, which can be
 “invoked” by a standard key or mouse command.  These portions are called
-“buttons”.  The default commands for activating a button are:
-
-‘<RET>’
-      -- Command: widget-button-press POS &optional EVENT
-          Invoke the button at POS, defaulting to point.  If point is
-          not located on a button, invoke the binding in
-          ‘widget-global-map’ (by default the global map).
-
-‘mouse-2’
-      -- Command: widget-button-click 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 ‘widget-global-map’ (by default the global
-          map).
+“buttons”.  The default commands for activating a button are
+‘widget-button-press’ and ‘widget-button-click’.  The user typically
+interacts with the buttons with a key, like <RET>, or with the mouse
+buttons.
 
    There are several different kind of buttons, all of which are present
 in the example:
@@ -245,28 +237,16 @@
      main difference from the ‘link’ widget is that the buttons will be
      displayed as GUI buttons when possible.
 
-   To make them easier to locate, buttons are emphasized in the buffer.
-
- -- Face: widget-button-face
-     Face used for buttons.
-
- -- User Option: widget-mouse-face
-     Face used for highlighting a button when the mouse pointer moves
-     across it.
+   To make them easier to locate, buttons are emphasized in the buffer
+with a distinctive face, like ‘widget-button-face’ or
+‘widget-mouse-face’.
 
 2.3 Navigation
 ==============
 
 You can use all the normal Emacs commands to move around in a form
-buffer, plus you will have these additional commands:
-
-‘<TAB>’
-      -- Command: widget-forward &optional count
-          Move point COUNT buttons or editing fields forward.
-‘M-<TAB>’
-‘S-<TAB>’
-      -- Command: widget-backward &optional count
-          Move point COUNT buttons or editing fields backward.
+buffer, plus you will have these additional commands to navigate from
+widget to widget: ‘widget-forward’ and ‘widget-backward’.
 
 3 Programming Example
 *********************
@@ -364,68 +344,474 @@
        (use-local-map widget-keymap)
        (widget-setup))
 
-4 Setting Up the Buffer
-***********************
+4 Widgets Basics
+****************
 
-Widgets are created with ‘widget-create’, which returns a “widget”
-object.  This object can be queried and manipulated by other widget
-functions, until it is deleted with ‘widget-delete’.  After the widgets
-have been created, ‘widget-setup’ must be called to enable them.
-
- -- Function: widget-create type [ keyword argument ]...
-     Create and return a widget of type TYPE.  The syntax for the TYPE
-     argument is described in *note Basic Types::.
+The Widget Library deals with widgets objects.  A widget object has
+properties whose value may be anything, be it numbers, strings, symbols,
+functions, etc.  Those properties are referred to as keywords and are
+responsible for the way a widget is represented in a buffer, and control
+the way a user or a program can interact with it.
+
+   The library defines several widget types, and gives you a way to
+define new types as well.  In addition, widgets can derive from other
+types, creating a sort of widget inheritance.  In fact, all widgets
+defined in the Widget Library share a common parent, the “default”
+widget.  In this manual, when we talk about a default behavior, we
+usually mean the behavior as defined by this ‘default’ widget.  *Note
+Widget Gallery::, for a description of each defined widget.
+
+   Defining a new type that derives from a previous one is not mandatory
+to create widgets that work very different from a specified type.  When
+creating a widget, you can override any default property, including
+functions, that control the widget.  That is, you can specialize a
+widget on creation, without having to define it as a new type of widget.
+
+   In addition to the function for defining a widget, this library
+provides functions to create widgets, query and change its properties,
+respond to user events and destroy them.  The following sections
+describe them.
+
+   One important property of a widget is its “value”.  All widgets may
+have a value, which is stored in a so-called “internal format”.  For the
+rest of Emacs, the widget presents its value in a so-called “external
+format”.  Both formats can be equal or different, and each widget is
+responsible for defining how the conversion between each format should
+happen.
+
+   The value property is an important property for almost all widgets,
+and perhaps more important for ‘editable-field’ widgets.  This type of
+widgets allow the user to edit them via the usual editing commands in
+Emacs.  They can also be edited programmatically.  *Important:* You
+_must_ call ‘widget-setup’ after modifying the value of a widget before
+the user is allowed to edit the widget again.  It is enough to call
+‘widget-setup’ once if you modify multiple widgets.  This is currently
+only necessary if the widget contains an editing field, but may be
+necessary for other widgets in the future.
 
-     The keyword arguments can be used to overwrite the keyword
-     arguments that are part of TYPE.
+   If your application needs to associate some information with the
+widget objects, for example a reference to the item being edited, it can
+be done with the ‘widget-put’ and ‘widget-get’ functions.  The property
+names, as shown, are keywords, so they must begin with a ‘:’.
 
- -- Function: widget-delete widget
-     Delete WIDGET and remove it from the buffer.
+5 Setting Up the Buffer
+***********************
+
+To show the widgets in a buffer, you have to create them.  Widget
+creation is actually a two-step process: conversion and creation per se.
+With simple projects, usually the conversion step isn’t really
+important, and you only care about widget creation, so feel free to skip
+the conversion description until you really need to know it.
+
+   Widget conversion is the process that involves taking a widget
+specification and transforming it into a “widget” object, suitable to be
+created, queried and manipulated with other widget functions.  Widget
+creation is the process that takes a widget object and actually inserts
+it in the buffer.
+
+   The simplest function to create a widget is ‘widget-create’, which
+gets a widget specification and returns a widget object.
+
+ -- Function: widget-create type [ keyword argument ]... args
+     Create and return a widget of type TYPE, converting it.
+
+     TYPE is a symbol that specifies a widget type.  KEYWORD may be one
+     of the properties supported by the widget type, and ARGUMENT
+     specify the value for that property.  These keyword arguments can
+     be used to overwrite the keyword arguments that are part of TYPE by
+     default, as well as to provide other properties not present in TYPE
+     by default.  ARGS holds additional information for the creation of
+     TYPE and each widget type is responsible for handling that
+     information in a specific way.
+
+     The syntax for the TYPE argument is described in *note Widget
+     Gallery::, and in more detail in every widget where it’s relevant.
+
+   There are other functions for creating widgets, useful when you work
+with composite widgets.  That is, widgets that are part of other
+widgets.
+
+ -- Function: widget-create-child-and-convert parent type &rest args
+     Create a widget of type TYPE as a child of PARENT.
+
+     Before creating it, converts TYPE using the keyword arguments
+     provided in ARGS.  Adds the ‘:indent’ property, unless it is
+     already present, and sets it to the sum of the values of: ‘:indent’
+     and ‘:offset’ from PARENT and ‘:extra-offset’ from TYPE.
+
+     Returns a widget object, with the property ‘:parent’ set to PARENT.
+
+ -- Function: widget-create-child parent type
+     Create a widget of type TYPE as a child of PARENT.
+
+     This function is like ‘widget-create-child-and-convert’ but it
+     doesn’t convert TYPE, so it expects an already converted widget.
+
+ -- Function: widget-create-child-value parent type value
+     Create a widget of type TYPE as a child of PARENT with value VALUE.
+
+     This function is like ‘widget-create-child’, but it lets you
+     specify a value for the widget.
+
+     Converts VALUE to the internal format, as specified by TYPE, and
+     stores it into the ‘:value’ property of TYPE.  That means, VALUE
+     should be in the external format, as specified by TYPE.
+
+   All these creating functions described here use the function stored
+in the ‘:create’ property.  So, to modify the creation logic for a
+widget, you can provide a different ‘:create’ function.
+
+   When you’re done creating widgets and you’re ready for the user to
+interact with the buffer, use the function ‘widget-setup’.
 
  -- Function: widget-setup
-     Set up a buffer to support widgets.
+     Setup the current buffer, so that editable widgets can be edited.
 
      This should be called after creating all the widgets and before
      allowing the user to edit them.
 
-   If you want to insert text outside the widgets in the form, the
-recommended way to do that is with ‘widget-insert’.
+   As mentioned, all these functions return a widget object.  That
+widget object can be queried and manipulated with widget functions that
+take widgets as arguments, until deleting it with the widgets functions
+available to delete widgets.  Even if you don’t save the returned widget
+object, you still can interact programmatically with the widget.  *Note
+Working with Widgets::.
+
+ -- Function: widget-delete widget
+     Delete the widget WIDGET and remove it from the buffer.
+
+ -- Function: widget-children-value-delete widget
+     Delete all children and buttons in widget WIDGET.
+
+     This function does not delete WIDGET itself, only the widgets
+     stored in the ‘:children’ and ‘:buttons’ properties.  It also sets
+     those properties to ‘nil’.
+
+   As with the creation mechanism, the function stored in ‘:delete’
+controls the deletion mechanism for a widget.
+
+   Additionally, the library provides a way to make a copy of a widget.
+
+ -- Function: widget-copy widget
+     Makes a copy of widget WIDGET and returns it.
+
+     It uses the function stored in the ‘:copy’ property of WIDGET and
+     returns the widget that that function returns.
+
+   As discussed, there is a conversion step when creating a widget.  To
+do the conversion without actually creating the widget, you can use the
+‘widget-convert’ function.
+
+ -- Function: widget-convert type &rest args
+     Convert TYPE to a widget object, using keyword arguments ARGS.
+
+     Returns a widget object, suitable for creation.  It calls the
+     function stored in the ‘:convert-widget’ property, after putting
+     into the ‘:args’ property the arguments that the widget in question
+     needs.  If TYPE has a ‘:value’ property, either originally or after
+     doing the conversion, this function converts the value stored in
+     ‘:value’ to the internal format, and stores it into ‘:value’.
+
+   Apart from only creating widgets in the buffer, It’s useful to have
+plain text.  For inserting text, the recommended way is with the
+‘widget-insert’ function.
+
+ -- Function: widget-insert &rest args
+     Insert ARGS, either strings or characters, at point.
+
+     Uses ‘insert’ to perform the insertion, passing ARGS as argument.
+     *Note (elisp)Insertion::, for more information about ARGS.
+
+     The resulting text will be read-only.
+
+6 Working with Widgets
+**********************
+
+This section covers the more important functions needed to query and
+manipulate widgets in a generic way.  Widgets may have additional
+functions for interacting with them, those are described in the
+description for each widget.  *Note Widget Gallery::.
+
+ -- Function: widgetp widget
+     Non-‘nil’ if WIDGET is a widget.
+
+ -- Function: widget-type widget
+     Return the type of widget WIDGET, a symbol.
+
+     This function is useful to find out which kind of widget WIDGET
+     represents, i.e., the name of the widget type when the widget was
+     created.
+
+ -- Function: widget-member widget property
+     Non-‘nil’ if widget WIDGET has a value (even ‘nil’) for property
+     PROPERTY.
+
+ -- Function: widget-get widget property
+     For widget WIDGET, return the value of the property PROPERTY.
+
+     PROPERTY should be a keyword, and the value is what was last set by
+     ‘widget-put’ for PROPERTY.
+
+ -- Function: widget-put widget property value
+     For widget WIDGET, set the property PROPERTY to VALUE.  PROPERTY
+     should be a keyword, while VALUE can be anything.
+
+ -- Function: widget-at &optional pos
+     Return the widget at position POS, or at point if POS is ‘nil’.
+
+ -- Function: widget-field-at pos
+     Return the widget field at position POS, or ‘nil’ if there is none.
+
+ -- Function: widget-apply widget property &rest args
+     Apply the function stored in PROPERTY to WIDGET, passing ARGS as
+     additional arguments to the function.
+
+     Returns the result of that function call.
+
+ -- Function: widget-value widget
+     Return the current value contained in WIDGET.
+
+     Note that the value returned by this function might differ from
+     what’s stored in the ‘:value’ property of WIDGET.  This is because
+     this function extracts the current value of WIDGET from the buffer,
+     taking editions into account.
+
+     The value returned is in the external format, after getting it with
+     the ‘:value-get’ function.
+
+     It is an error to call this function on an uninitialized widget.
+
+ -- Function: widget-value-set widget value
+     Set the value contained in WIDGET to VALUE.
+
+     Converts VALUE to the internal format, and then sets it by applying
+     the ‘:value-set’ function.
+
+     It is an error to call this function with an invalid VALUE, that
+     is, a value that WIDGET cannot represent.
+
+ -- Function: widget-default-get widget
+     Return the default external value of widget WIDGET.
+
+     The default value is the one stored in ‘:value’ or the result of
+     applying the ‘:default-get’ function to the arguments of WIDGET, as
+     stored in ‘:args’.  A value of ‘nil’ is ignored by default, so in
+     order for a widget to respect ‘nil’ as a value, it has to override
+     the ‘:default-get’ function.
+
+ -- Function: widget-type-default-get widget
+     Convert the ‘:type’ attribute in WIDGET and return its default
+     value.
+
+ -- Function: widget-child-value-get widget
+     Return the value of the first member of ‘:children’ in WIDGET.
+
+ -- Function: widget-child-value-inline widget
+     Return the inline value of the first member of ‘:children’ in
+     WIDGET.
+
+     The inline value is whatever the function stored in ‘:value-inline’
+     returns.
+
+ -- Function: widget-type-value-create widget
+     Create a child widget for WIDGET, of type stored in ‘:type’.
+
+     Creates the child widget taking the value from the ‘:value’
+     property and stores the newly created widget in the ‘:children’
+     property of WIDGET.
+
+     The value stored in ‘:type’ should be an unconverted widget type.
 
- -- Function: widget-insert
-     Insert the arguments, either strings or characters, at point.  The
-     inserted text will be read-only.
+ -- Function: widget-value-convert-widget widget
+     Initializes the ‘:value’ property of WIDGET from ‘:args’.
 
-   There is a standard widget keymap which you might find useful.
+     Sets ‘:args’ to ‘nil’ and returns the modified widget WIDGET.
+
+ -- Function: widget-value-value-get widget
+     Return the value stored in ‘:value’ for widget WIDGET.
+
+     This is different to getting the current value for WIDGET with
+     ‘widget-value’, since that function extracts the value from the
+     buffer.
+
+ -- Function: widget-apply-action widget &optional event
+     Apply the function stored in ‘:action’ to WIDGET, in response to
+     EVENT.
+
+     It is an error to call this function with an inactive widget.
+
+ -- Function: widget-parent-action widget &optional event
+     Tell ‘:parent’ of WIDGET to handle EVENT.
+
+     Optional EVENT is the event that triggered the action.
+
+ -- Function: widget-child-validate widget
+     Check that the first member of ‘:children’ in WIDGET is valid.
+
+     To be valid means that the widget value passes the checks that the
+     function stored in ‘:validate’ makes.
+
+ -- Function: widget-children-validate widget
+     Check that all ‘:children’ in WIDGET are valid.
+
+     Returns ‘nil’ on success, or the first child that isn’t valid.
+
+ -- Function: widget-type-match widget value
+     Return non-‘nil’ if VALUE matches the value for the ‘:type’ widget.
+
+     As with the other type functions, the widget stored in ‘:type’
+     should be an unconverted widget.
+
+ -- Function: widget-types-copy widget
+     Copy the ‘:args’ value in WIDGET and store them in ‘:args’.
+
+     Makes the copies by calling ‘widget-copy’ on each element present
+     in ‘:args’.  Returns the modified widget WIDGET.
+
+ -- Function: widget-types-convert-widget widget
+     Convert the ‘:args’ value in WIDGET and store them in ‘args’.
+
+     Returns the modified widget WIDGET.
+
+7 Widgets and the Buffer
+************************
+
+This chapter describes commands that are specific to buffers that
+contain widgets.
 
  -- Const: widget-keymap
-     <TAB> and ‘C-<TAB>’ are bound to ‘widget-forward’ and
-     ‘widget-backward’, respectively.  <RET> and ‘mouse-2’ are bound to
-     ‘widget-button-press’ and ‘widget-button-click’.
+     Keymap containing useful bindings for buffers containing widgets.
+
+     Binds <TAB> and ‘C-<TAB>’ to ‘widget-forward’ and
+     ‘widget-backward’, respectively.  It also binds <RET> to
+     ‘widget-button-press’ and ‘down-mouse-1’ and ‘down-mouse-2’ to
+     ‘widget-button-click’.
+
+   There’s also a keymap for events that the widget library doesn’t need
+to handle.
 
  -- Variable: widget-global-map
      Keymap used by ‘widget-button-press’ and ‘widget-button-click’ when
      not on a button.  By default this is ‘global-map’.
 
-5 Basic Types
-*************
+   In addition to these two keymaps, each widget might define a keymap
+of its own, active when events happen at that widget.
+
+   The following navigation commands are available:
+
+‘<TAB>’
+      -- Command: widget-forward &optional count
+          Move point COUNT buttons or editing fields forward.
+‘M-<TAB>’
+‘S-<TAB>’
+      -- Command: widget-backward &optional count
+          Move point COUNT buttons or editing fields backward.
+
+   When editing an ‘editable-field’ widget, the following commands are
+available:
+
+‘<C-e>’
+      -- Command: widget-end-of-line
+          Move point to the end of field or end of line, whichever is
+          first.
+
+‘C-k’
+      -- Command: widget-kill-line
+          Kill to end of field or end of line, whichever is first.
+
+‘M-TAB’
+      -- Command: widget-complete
+          Complete the content of the editable field at point.
+
+‘C-m’
+      -- Command: widget-field-activate
+          Invoke the editable field at point.
+
+   The following two are commands that can execute widget actions.
+‘<RET>’
+      -- Command: widget-button-press POS &optional EVENT
+          Invoke the button at POS, defaulting to point.
 
-This is the general syntax of a type specification:
+          Invocation means to run the function stored in the ‘:action’
+          property.
+
+          If point is not located on a button, invoke the binding in
+          ‘widget-global-map’ (by default the global map).
+
+‘mouse-2’
+      -- Command: widget-button-click 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 ‘widget-global-map’ (by default the
+          global map).
+
+          In case the mouse-click is on a widget, calls the function
+          stored in the ‘:mouse-down-action’ property.
+
+8 Widget Gallery
+****************
+
+All widgets can be created from a type specification.  The general
+syntax of a type specification is:
 
      NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
           |   NAME
 
-   Where, NAME is a widget name, KEYWORD is the name of a property,
-ARGUMENT is the value of the property, and ARGS are interpreted in a
-widget specific way.
+   Where NAME is a widget name, as defined with ‘define-widget’, KEYWORD
+is the name of a property and ARGUMENT is the value for that property,
+and ARGS are interpreted in a widget specific way.  *Note Defining New
+Widgets::.
+
+   The most basic widget in the Widget Library is the “default” widget.
+It provides the basic behavior for all other widgets, and all its
+properties are present by default in derived widgets.  You’re seldom (if
+ever) going to effectively create a default widget, but here we describe
+its properties and behavior, so that we can describe other widgets only
+by mentioning the properties and behavior those other widgets
+specialize.
+
+ -- Widget: default
+     Widget used as a base for other widgets.
+
+     It provides most of the functionality that is referred to as “by
+     default” in this text.  If you want to define a new widget from
+     scratch, use the ‘default’ widget as its base.
 
    The following keyword arguments apply to all widgets:
 
+‘: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.
+
+     By default, it inserts the widget at point, using the format
+     provided in the ‘:format’ property.
+
+‘:delete’
+     Function to delete a widget.
+
+     The function should take one argument, a widget, and should remove
+     all traces of the widget from the buffer.
+
+     The default value is:
+
+      -- Function: widget-default-delete widget
+          Remove WIDGET from the buffer.  Delete all ‘:children’ and
+          ‘:buttons’ in WIDGET.
+
+     In most cases you should not change this value, but instead use
+     ‘:value-delete’ to make any additional cleanup.
+
 ‘:value’
-     The initial value for widgets of this type.  Typically, a widget
-     represents its value in two formats: external and internal.  The
-     external format is the value as the rest of Emacs sees it, and the
-     internal format is a representation that the widget defines and
-     uses in a widget specific way.
+     The initial value for widgets of this type.
+
+     Typically, a widget represents its value in two formats: external
+     and internal.  The external format is the value as the rest of
+     Emacs sees it, and the internal format is a representation that the
+     widget defines and uses in a widget specific way.
 
      Both formats might be the same for certain widgets and might differ
      for others, and there is no guarantee about which format the value
@@ -433,6 +819,59 @@
      widget or defining a new one (*note Defining New Widgets::), the
      ‘:value’ should be in the external format.
 
+‘: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 internal value.  The function is called on the
+     present ‘:value’ when the widget is created, and on any value set
+     later with ‘widget-value-set’.
+
+‘: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 value in the external format.
+
+‘:value-create’
+     Function to expand the ‘%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.
+
+‘:value-delete’
+     A function that 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 remove the text, but it should release markers and delete nested
+     widgets if these are not listed in ‘:children’ or ‘:buttons’.
+
+     By default, it’s a no-op.
+
+‘:value-get’
+     Function to extract the value of a widget, as it is displayed in
+     the buffer.
+
+‘:value-set’
+     Function that takes a widget and a value as arguments, and
+     recreates it.
+
+     The value must already be in the internal format for widget.  By
+     default, it deletes the widget with the ‘:delete’ function and
+     creates it again with the ‘:create’ function.
+
+‘:value-inline’
+     Function that takes a widget and returns its value, inlined.
+
+     Inlined means that if the widget is not inline (i.e., its ‘:inline’
+     property is ‘nil’), the return value is wrapped in a list.
+
+‘:default-get’
+     Function that takes a widget and returns its default value.
+
+     By default, it just returns the value stored in ‘:value’.
+
 ‘:format’
      This string will be inserted in the buffer when you create a
      widget.  The following ‘%’ escapes are available:
@@ -444,12 +883,6 @@
           By default, the text will be shown in ‘widget-button-face’,
           and surrounded by brackets.
 
-           -- User Option: widget-button-prefix
-               String to prefix buttons.
-
-           -- User Option: widget-button-suffix
-               String to suffix buttons.
-
      ‘%{’
      ‘%}’
           The text inside will be displayed with the face specified by
@@ -459,10 +892,6 @@
           This will be replaced with the buffer representation of the
           widget’s value.  What this is depends on the widget type.
 
-          *Warning:* In an ‘editable-field’ widget, the ‘%v’ escape must
-          be preceded by some other text in the format string (if
-          specified).
-
      ‘%d’
           Insert the string specified by ‘:doc’ here.
 
@@ -489,6 +918,11 @@
 
 ‘:button-prefix’
 ‘:button-suffix’
+     Strings used as prefix and suffix for widgets that are buttons.
+
+     By default, the values are ‘widget-button-prefix’ and
+     ‘widget-button-suffix’.
+
      Text around %[ %] in the format.
 
      These can be
@@ -514,10 +948,11 @@
 ‘:help-echo’
      Specifies how to display a message whenever you move to the widget
      with either ‘widget-forward’ or ‘widget-backward’ or move the mouse
-     over it (using the standard ‘help-echo’ mechanism).  The argument
-     is either a string to display, a function of one argument, the
-     widget, which should return a string to display, or a form that
-     evaluates to such a string.
+     over it (using the standard ‘help-echo’ mechanism).
+
+     The value is either a string to display, or a function of one
+     argument, the widget.  If a function, it should return a string to
+     display, or a form that evaluates to such a string.
 
 ‘:follow-link’
      Specifies how to interpret a <mouse-1> click on the widget.  *Note
@@ -525,7 +960,12 @@
 
 ‘:indent’
      An integer indicating the absolute number of spaces to indent
-     children of this widget.
+     children of this widget.  Its value might be ‘nil’ too, which
+     corresponds to a value of 0.
+
+     The default ‘:create’ functions and the functions that create the
+     value per se use this property as a rudimentary layout mechanism
+     for the widgets.
 
 ‘:offset’
      An integer indicating how many extra spaces to add to the widget’s
@@ -535,22 +975,17 @@
      An integer indicating how many extra spaces to add to the widget’s
      children compared to this widget.
 
-‘: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 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.
-
 ‘:menu-tag’
      Tag used in the menu when the widget is used as an option in a
      ‘menu-choice’ widget.
 
 ‘:menu-tag-get’
-     Function used for finding the tag when the widget is used as an
-     option in a ‘menu-choice’ widget.  By default, the tag used will be
-     either the ‘:menu-tag’ or ‘:tag’ property if present, or the
-     ‘princ’ representation of the ‘:value’ property if not.
+     Function that takes a widget and returns the tag when the widget is
+     used as an option in a ‘menu-choice’ widget.
+
+     By default, the tag used will be either the ‘:menu-tag’ or ‘:tag’
+     property if present, or the ‘princ’ representation of the ‘:value’
+     property if not.
 
 ‘:match’
      Should be a function called with two arguments, the widget and an
@@ -559,20 +994,18 @@
 
 ‘:validate’
      A function which takes a widget as an argument, and returns ‘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 ‘:error’ property to a string explaining the error.
+     if the widget’s current value is valid for the widget.
 
-     The following predefined function can be used:
+     Otherwise, it should return the widget containing the invalid data,
+     and set that widget’s ‘:error’ property to a string explaining the
+     error.
 
-      -- Function: widget-children-validate widget
-          All the ‘:children’ of WIDGET must be valid.
+     By default, it always returns ‘nil’.
 
 ‘:tab-order’
      Specify the order in which widgets are traversed with
      ‘widget-forward’ or ‘widget-backward’.  This is only partially
      implemented.
-
        a. Widgets with tabbing order ‘-1’ are ignored.
 
        b. (Unimplemented) When on a widget with tabbing order N, go to
@@ -593,134 +1026,508 @@
      arguments, which will be used when creating the ‘radio-button’ or
      ‘checkbox’ associated with this item.
 
- -- User Option: widget-image-directory
-     Directory where Widget should look for images.  Widget will look
-     here for a file with the same name as specified for the image, with
-     either a ‘.xpm’ (if supported) or ‘.xbm’ extension.
+‘:completions-function’
+     Function that takes a widget and returns completion data for that
+     widget, like ‘completion-at-point-functions’ would.  *Note
+     (elisp)Completion::.  It’s used by ‘editable-field’ widgets to
+     provide completions.
+
+     By default, it looks into the property ‘:completions’, which should
+     be a completion table.  If ‘:completions’ is ‘nil’, then it calls
+     the function stored either in the ‘:complete’ or
+     ‘:complete-function’ property.
 
- -- User Option: widget-image-enable
-     If non-‘nil’, allow images to appear on displays where they are
-     supported.
+‘:format-handler’
+     Function to handle unknown ‘%’ escapes in the format string.
+
+     It takes a widget and the character that follows the ‘%’ as
+     arguments.  You can set this to allow your widget to handle
+     non-standard escapes in your own specialized widgets.
+
+     You should end up calling ‘widget-default-format-handler’ to handle
+     unknown escape sequences, which will handle the ‘%h’ and any future
+     escape sequences, as well as give an error for unknown escapes.
+
+‘:button-face-get’
+     Function to return the face used to fontify a widget button.
+
+     Takes a widget and returns an appropriate face for the widget.  By
+     default, it either returns the face stored in the ‘:button-face’
+     property, or calls the ‘:button-face-get’ function from the parent
+     of the widget, if it has one.
+
+‘:mouse-face-get’
+     Function to return the face used to fontify a widget when the mouse
+     pointer hovers over it.
+
+     Takes a widget and returns an appropriate face.  By default, it
+     either returns the face stored in the ‘:mouse-face’ property, or
+     calls the ‘:button-face-get’ function from the parent of the
+     widget, if it has one.
+
+‘:copy’
+     Function to deep copy a widget type.
+
+     It takes a shallow copy of the widget type as an argument (made by
+     ‘copy-sequence’), and returns a deep copy.  The purpose of this is
+     to avoid having different instances of combined widgets share
+     nested attributes.
+
+     Its value by default is ‘identity’.
+
+‘:active’
+     Function that takes a widget and returns ‘t’ if it is active.
+
+     A widget might be effectively always active, if its
+     ‘:always-active’ property is ‘t’.
+
+     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:
+
+          ;; Examine if WIDGET is active or not.
+          (if (widget-apply WIDGET :active)
+              (message "Widget is active.")
+            (message "Widget is inactive.")
+
+          ;; Make WIDGET inactive.
+          (widget-apply WIDGET :deactivate)
+
+          ;; Make WIDGET active.
+          (widget-apply WIDGET :activate)
+
+     A widget is inactive if it, or any of its ancestors (found by
+     following the ‘:parent’ link), have been deactivated.  To make sure
+     a widget is really active, you must therefore activate both it and
+     all its ancestors.
+
+          (while widget
+            (widget-apply widget :activate)
+            (setq widget (widget-get widget :parent)))
+
+     You can check if a widget has been made inactive by examining the
+     value of the ‘:inactive’ keyword.  If this is non-‘nil’, the widget
+     itself has been deactivated.  This is different from using the
+     ‘:active’ keyword, in that the latter tells you if the widget *or*
+     any of its ancestors have been deactivated.  Do not attempt to set
+     the ‘:inactive’ keyword directly.  Use the ‘:activate’
+     ‘:deactivate’ functions instead.
+
+‘:activate’
+     Function that takes a widget and makes it active for user
+     modifications.
+
+‘:deactivate’
+     Function that takes a widget and makes it inactive for user
+     modifications.
+
+‘:action’
+     Function that takes a widget and optionally an event, and handles a
+     user initiated event.
+
+     By default, uses the ‘:notify’ function to notify the widget’s
+     parent about the event.
+
+‘:mouse-down-action’
+     Function that takes a widget and optionally an event, and handles a
+     mouse click on the widget.
+
+     By default, it does nothing.
+
+‘: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 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.
+
+     By default, it passes the notification to the widget’s parent.
+
+‘:prompt-value’
+     Function to prompt for a value in the minibuffer.
+
+     The function should take four arguments, a widget, a prompt (a
+     string), a value and a boolean, and should return a value for the
+     widget, entered by the user.
+
+     The prompt is the prompt to use.  The value is the default value to
+     use, unless the fourtha argument is non-‘nil’, in which case there
+     is no default value.
+
+     The function should read the value using the method most natural
+     for this widget, and does not have to check that it matches.
+
+8.1 Basic Types
+===============
+
+8.1.1 The ‘item’ Widget
+-----------------------
+
+Syntax:
+
+     TYPE ::= (item [KEYWORD ARGUMENT]... VALUE)
 
-5.1 The ‘link’ Widget
-=====================
+   A useful widget that holds a constant value, and can be included in
+other widgets.  Its super is the ‘default’ widget.
+
+   As can be seen in the syntax, the ‘item’ widget is one of the widget
+that handles the ARGS argument to ‘widget-create’ in a specific way.  If
+present, VALUE is used to initialize the ‘:value’ property.  When
+created, it inserts the value as a string in the buffer.
+
+   By default, it has the following properties:
+
+‘:convert-widget’
+     The function that allows it to handle VALUE.
+
+‘:value-create’
+     Prints the representation of ‘:value’ in the buffer.
+
+‘:value-get’
+     Returns the value stored in ‘:value’.
+
+‘:match’
+     A value matches the ‘item’ widget if it’s ‘equal’ to its ‘:value’.
+
+‘:match-inline’
+     Inline values match the ‘item’ widget if ‘:value’ is a sublist of
+     values.
+
+‘:action’
+     The ‘item’ widget notifies itself of an event.
+
+‘:format’
+     By default, the ‘item’ widget inserts its tag in the buffer.
+
+8.1.2 The ‘link’ Widget
+-----------------------
 
 Syntax:
 
      TYPE ::= (link [KEYWORD ARGUMENT]...  [ VALUE ])
 
+   A widget to represent an embedded link.  Its super is the ‘item’
+widget.
+
    The VALUE, if present, is used to initialize the ‘:value’ property.
 The value should be a string, which will be inserted in the buffer.
 
-   By default the link will be shown in brackets.
+   By default, it has the following properties:
 
- -- User Option: widget-link-prefix
-     String to prefix links.
+‘:button-prefix’
+     The value of ‘widget-link-prefix’.
 
- -- User Option: widget-link-suffix
-     String to suffix links.
+‘:button-suffix’
+     The value of ‘widget-link-suffix’.
+
+‘:keymap’
+     A custom keymap for the link widget, so that it can respond to
+     mouse clicks.
+
+‘:follow-link’
+     This property allows the link to respect the value of
+     ‘mouse-1-click-follows-link’.  *Note (elisp)Clickable Text::.
+
+‘:format’
+     Buttonizes the link, to make it clickable.
+
+     If you override this property, you should make sure to provide the
+     ‘%[’ and ‘%]’ escape sequences, so that the link is clickable.
+
+   By default the link will be shown in brackets.
 
-5.2 The ‘url-link’ Widget
-=========================
+8.1.3 The ‘url-link’ Widget
+---------------------------
 
 Syntax:
 
      TYPE ::= (url-link [KEYWORD ARGUMENT]...  URL)
 
-   When this link is invoked, the WWW browser specified by
-‘browse-url-browser-function’ will be called with URL.
+   A widget to represent a link to a web page.  Its super is the ‘link’
+widget.
+
+   It overrides the ‘:action’ property to open up the URL specified.
 
-5.3 The ‘info-link’ Widget
-==========================
+8.1.4 The ‘info-link’ Widget
+----------------------------
 
 Syntax:
 
      TYPE ::= (info-link [KEYWORD ARGUMENT]...  ADDRESS)
 
-   When this link is invoked, the built-in Info reader is started on
-ADDRESS.
+   A widget to represent a link to an info file.  Its super is the
+‘link’ widget.
+
+   It overrides the ‘:action’ property, to a function to start the
+built-in Info reader on ADDRESS, when invoked.
 
-5.4 The ‘push-button’ Widget
-============================
+8.1.5 The ‘function-link’ Widget
+--------------------------------
+
+Syntax:
+
+     TYPE ::= (function-link [KEYWORD ARGUMENT]...  FUNCTION)
+
+   A widget to represent a link to an Emacs function.  Its super is the
+‘link’ widget.
+
+   It overrides the ‘:action’ property, to a function to describe
+FUNCTION.
+
+8.1.6 The ‘variable-link’ Widget
+--------------------------------
+
+Syntax:
+
+     TYPE ::= (variable-link [KEYWORD ARGUMENT]...  VAR)
+
+   A widget to represent a link to an Emacs variable.  Its super is the
+‘link’ widget.
+
+   It overrides the ‘:action’ property, to a function to describe VAR.
+
+8.1.7 The ‘face-link’ Widget
+----------------------------
+
+Syntax:
+
+     TYPE ::= (face-link [KEYWORD ARGUMENT]...  FACE)
+
+   A widget to represent a link to an Emacs face.  Its super is the
+‘link’ widget.
+
+   It overrides the ‘:action’ property, to a function to describe FACE.
+
+8.1.8 The ‘file-link’ Widget
+----------------------------
+
+Syntax:
+
+     TYPE ::= (file-link [KEYWORD ARGUMENT]...  FILE)
+
+   A widget to represent a link to a file.  Its super is the ‘link’
+widget.
+
+   It overrides the ‘:action’ property, to a function to find the file
+FILE.
+
+8.1.9 The ‘emacs-library-link’ Widget
+-------------------------------------
+
+Syntax:
+
+     TYPE ::= (emacs-library-link [KEYWORD ARGUMENT]...  FILE)
+
+   A widget to represent a link to an Emacs Lisp file.  Its super is the
+‘link’ widget.
+
+   It overrides the ‘:action’ property, to a function to find the file
+FILE.
+
+8.1.10 The ‘emacs-commentary-link’ Widget
+-----------------------------------------
+
+Syntax:
+
+     TYPE ::= (emacs-commentary-link [KEYWORD ARGUMENT]...  FILE)
+
+   A widget to represent a link to the Comment section of an Emacs Lisp
+file.  Its super is the ‘link’ widget.
+
+   It overrides the ‘:action’ property, to a function to find the file
+FILE and put point in the Comment section.
+
+8.1.11 The ‘push-button’ Widget
+-------------------------------
 
 Syntax:
 
      TYPE ::= (push-button [KEYWORD ARGUMENT]...  [ VALUE ])
 
+   A widget that acts as a pushable button.  Its super is the ‘item’
+widget.
+
    The VALUE, if present, is used to initialize the ‘:value’ property.
 The value should be a string, which will be inserted in the buffer.
 
-   By default the tag will be shown in brackets.
+   By default, it has the following properties:
+‘:button-prefix’
+     The empty string.
 
- -- User Option: widget-push-button-prefix
-     String to prefix push buttons.
+‘:button-suffix’
+     The empty string.
 
- -- User Option: widget-push-button-suffix
-     String to suffix push buttons.
+‘:value-create’
+     Inserts a representation of the “on” and “off” states for the push
+     button.
+
+     The representation might be an image, stored in the ‘:tag-glyph’
+     property, or text.  If it is text, it might be the value of the
+     ‘:tag’ property, or the ‘:value’ of the widget, surrounded with
+     ‘widget-push-button-prefix’ and ‘widget-push-button-suffix’.  *Note
+     Customization::.
 
-5.5 The ‘editable-field’ Widget
-===============================
+‘:format’
+     Buttonizes the widget, to make it clickable.
+
+8.1.12 The ‘editable-field’ Widget
+----------------------------------
 
 Syntax:
 
      TYPE ::= (editable-field [KEYWORD ARGUMENT]... [ VALUE ])
 
+   A widget that can be edited by the user.  Its super is the ‘default’
+widget.
+
    The VALUE, if present, is used to initialize the ‘:value’ property.
-The value should be a string, which will be inserted in the field.  This
-widget will match all string values.
+The value should be a string, which will be inserted in the field.  If
+not present, ‘:value’ is the empty string.
 
-   The following extra properties are recognized:
+   *Warning:* In an ‘editable-field’ widget, the editable field must not
+be adjacent to another widget—that won’t work.  You must put some text
+in between.  Either make this text part of the ‘editable-field’ widget
+itself, or insert it with ‘widget-insert’.
+
+   This widget either overrides or adds the following properties:
+
+‘:convert-widget’
+     Just like the ‘item’ widget, this function allows it to initialize
+     ‘:value’ from VALUE.
+
+‘:keymap’
+     Keymap used in the editable field.
+
+     The default value is ‘widget-field-keymap’, which allows the user
+     to use all the normal editing commands, even if the buffer’s major
+     mode suppresses some of them.  Pressing <RET> invokes the function
+     specified by ‘:action’.
+
+‘:format’
+     By default, it specifies to insert only the widget’s value.
+
+     *Warning:* In an ‘editable-field’ widget, the ‘%v’ escape must be
+     preceded by some other text in the ‘:format’ string (if specified).
 
 ‘:size’
      The width of the editable field.
+
      By default the field will reach to the end of the line.
 
 ‘:value-face’
-     Face used for highlighting the editable field.  Default is
-     ‘widget-field-face’, see *note User Interface::.
+     Face used for highlighting the editable field.
+
+     Default is ‘widget-field-face’, *note User Interface::.
 
 ‘:secret’
-     Character used to display the value.  You can set this to, e.g.,
-     ‘?*’ if the field contains a password or other secret information.
-     By default, this is ‘nil’, and the value is not secret.
+     Character used to display the value.
+
+     You can set this to, e.g., ‘?*’ if the field contains a password or
+     other secret information.  By default, this is ‘nil’, and the value
+     is not secret.
 
 ‘:valid-regexp’
      By default the ‘:validate’ function will match the content of the
-     field with the value of this attribute.  The default value is ‘""’
-     which matches everything.
+     field with the value of this attribute.
+
+     The default value is ‘""’ which matches everything.
+
+‘:validate’
+     Returns ‘nil’ if the current value of the widget matches the
+     ‘:valid-regexp’ value.
+
+‘:prompt-internal’
+     A function to read a value for widget, used by the ‘:prompt-value’
+     function.
+
+‘:prompt-history’
+     A variable that holds the history of field minibuffer edits.
+
+‘:prompt-value’
+     A function that uses the ‘:prompt-internal’ function and the
+     ‘:prompt-history’ value to prompt for a string, and retun the user
+     response in the external format.
+
+‘:action’
+     When invoked, moves point to the next field.
+
+‘:value-create’
+     Function that takes care of creating the widget, respecting its
+     ‘:size’ and ‘:value’.
+
+‘:value-set’
+     Function to use to modify programatically the current value of the
+     widget.
+
+‘:value-delete’
+     Function that removes the widget so it cannot be edited anymore.
+
+‘:value-get’
+     Function to return the current text in the widget.
+
+     It takes an optional argument, NO-TRUNCATE.  If NO-TRUNCATE is nil,
+     truncates trailing spaces.
+
+‘:match’
+     Function that makes the widget match any string value.
+
+8.1.13 The ‘text’ Widget
+------------------------
+
+Syntax:
+
+     TYPE ::= (text [KEYWORD ARGUMENT]... [ VALUE ])
+
+   A widget just like the ‘editable-field’ widget, but intended for
+multiline text fields.  Its super is the ‘editable-field’ widget.
+
+   It overrides the following properties:
+
+‘:format’
+     By default, prints a tag and the value.
 
 ‘:keymap’
-     Keymap used in the editable field.  The default value is
-     ‘widget-field-keymap’, which allows you to use all the normal
-     editing commands, even if the buffer’s major mode suppresses some
-     of them.  Pressing <RET> invokes the function specified by
-     ‘:action’.
-
-5.6 The ‘text’ Widget
-=====================
-
-This is just like ‘editable-field’, but intended for multiline text
-fields.  The default ‘:keymap’ is ‘widget-text-keymap’, which does not
-rebind the <RET> key.
+     The default is ‘widget-text-keymap’, which does not rebind the
+     <RET> key.
 
-5.7 The ‘menu-choice’ Widget
-============================
+8.1.14 The ‘menu-choice’ Widget
+-------------------------------
 
 Syntax:
 
      TYPE ::= (menu-choice [KEYWORD ARGUMENT]... TYPE ... )
 
+   A widget to represent a menu of options.  Its super is the ‘default’
+widget.
+
    The TYPE argument represents each possible choice.  The widget’s
-value will be that of the chosen TYPE argument.  This widget will match
-any value matching at least one of the specified TYPE arguments.
+value will be that of the chosen TYPE argument.
+
+   It either overrides or adds the following properties:
+
+‘:convert-widget’
+     A function that takes care of converting each possible choice.
+
+‘:copy’
+     A function to copy each possible choice.
+
+‘:format’
+     By default, buttonize the tag and show the value.
 
 ‘:void’
      Widget type used as a fallback when the value does not match any of
      the specified TYPE arguments.
 
+     By default this is an ‘item’ widget.
+
 ‘:case-fold’
-     Set this to ‘nil’ if you don’t want to ignore case when prompting
-     for a choice through the minibuffer.
+     If ‘nil’ don’t ignore case when prompting for a choice through the
+     minibuffer.
+
+     By default, its value is ‘t’.
 
 ‘:children’
      A list whose CAR is the widget representing the currently chosen
@@ -732,19 +1539,77 @@
 ‘:args’
      The list of types.
 
-5.8 The ‘radio-button-choice’ Widget
-====================================
+‘:value-create’
+     The function that inserts the current value for the widget.
+
+     It inserts the first choice that matches, as with the ‘:match’
+     function, the value of the widget.
+
+‘:value-get’
+     Returns the value of the first child for the widget (see the
+     description for ‘:children’ above).
+
+‘:value-inline’
+     Returns the inline value of the first child for the widget.
+
+‘:default-get’
+     The default value for this widget is the default value for the
+     first choice, in case ‘:value’ is missing.
+
+     This means that if you want a specific default value for the
+     ‘menu-choice’ widget, you should either pass a ‘:value’ property
+     when creating it, or arrange the choices so that the first one can
+     hold your desired default value.
+
+‘:mouse-down-action’
+     A function that takes care of showing a menu, if possible and
+     desired.
+
+‘:action’
+     A function that takes care of getting a new choice for the widget.
+
+     Depending on the number of choices available, it may show a menu or
+     just toggle the choices, or even do nothing at all.
+
+     After getting the choice, it recreates the widget and notifies it.
+
+‘:validate’
+     Returns ‘nil’ if the widget’s value is a valid choice.
+
+‘:match’
+     This widget will match any value matching at least one of the
+     specified TYPE arguments.
+
+‘:match-inline’
+     A function that returns non-‘nil’ if the values match the widget,
+     taking into account the ‘:inline’ property.
+
+8.1.15 The ‘radio-button-choice’ Widget
+---------------------------------------
 
 Syntax:
 
      TYPE ::= (radio-button-choice [KEYWORD ARGUMENT]...  TYPE ... )
 
-   The component types specify the choices, with one radio button for
+   A widget to represent a choice from multiple options.  Its super is
+the ‘default’ widget.
+
+   The component TYPES specify the choices, with one radio button for
 each.  The widget’s value will be that of the chosen TYPE argument.
-This widget matches any value that matches at least one of the specified
-TYPE arguments.
 
-   The following extra properties are recognized.
+   It overrides the following properties:
+
+‘:convert-widget’
+     As other composite widgets, a function that takes care of
+     converting each available choice.
+
+‘:copy’
+     A function to copy each available choice.
+
+‘:action’
+     A function that checks if any radio button was pressed and
+     activates the pressed one, possibly deactivating an old one.  Then,
+     it notifies itself.
 
 ‘:entry-format’
      This string will be inserted for each entry in the list.  The
@@ -756,6 +1621,9 @@
      ‘%%’
           Insert a literal ‘%’.
 
+‘:format’
+     By default, it inserts its value.
+
 ‘:button-args’
      A list of keywords to pass to the radio buttons.  Useful for
      setting, e.g., the ‘:help-echo’ for each button.
@@ -767,11 +1635,37 @@
      The widgets representing each type.
 
 ‘:choice’
-     The current chosen type
+     The current chosen type.
 
 ‘:args’
      The list of types.
 
+‘:value-create’
+     A function to insert all available choices.
+
+‘:value-get’
+     Returns the value for the chosen widget.
+
+‘:value-set’
+     A function to set the value to one of its available options.
+
+‘:value-inline’
+     A function that returns the inline value of the child widget.
+
+‘:offset’
+     By default, this widget has an offset of 4.
+
+‘:validate’
+     The widget validates if the current value is valid for one of its
+     children.
+
+‘:match’
+     This widget matches any value that matches at least one of the
+     specified TYPE arguments.
+
+‘:match-inline’
+     Like the ‘:match’ function, but taking into account inline values.
+
    You can add extra radio button items to a ‘radio-button-choice’
 widget after it has been created with the function
 ‘widget-radio-add-item’.
@@ -784,77 +1678,172 @@
 widget has been created will *not* be properly destructed when you call
 ‘widget-delete’.
 
-5.9 The ‘item’ Widget
-=====================
+8.1.16 The ‘choice-item’ Widget
+-------------------------------
 
 Syntax:
 
-     ITEM ::= (item [KEYWORD ARGUMENT]... VALUE)
+     ITEM ::= (choice-item [KEYWORD ARGUMENT]... VALUE)
 
-   The VALUE, if present, is used to initialize the ‘:value’ property.
-The value should be a string, which will be inserted in the buffer.
-This widget will only match the specified value.
+   A widget to represent a choice in a ‘menu-choice’ widget.  Its super
+is the ‘item’ widget.
 
-5.10 The ‘choice-item’ Widget
-=============================
+   The VALUE, if present, is used to initialize the ‘:value’ property.
 
-Syntax:
+   It overrides the following properties:
 
-     ITEM ::= (choice-item [KEYWORD ARGUMENT]... VALUE)
+‘:action’
+     Activating the button of a ‘choice-item’ is equivalent to
+     activating the parent widget.
 
-   The VALUE, if present, is used to initialize the ‘:value’ property.
-The value should be a string, which will be inserted in the buffer as a
-button.  Activating the button of a ‘choice-item’ is equivalent to
-activating the parent widget.  This widget will only match the specified
-value.
+‘:format’
+     By default, it buttonizes the tag (i.e., its value) and adds a
+     newline character at the end of the widget.
 
-5.11 The ‘toggle’ Widget
-========================
+8.1.17 The ‘toggle’ Widget
+--------------------------
 
 Syntax:
 
      TYPE ::= (toggle [KEYWORD ARGUMENT]...)
 
+   A widget that can toggle between two states.  Its super is the ‘item’
+widget.
+
    The widget has two possible states, ‘on’ and ‘off’, which correspond
 to a ‘t’ or ‘nil’ value, respectively.
 
-   The following extra properties are recognized:
+   It either overrides or adds the following properties:
+
+‘:format’
+     By default, it buttonizes the value and adds a newline at the end
+     of the widget.
 
 ‘:on’
      A string representing the ‘on’ state.  By default the string ‘on’.
+
 ‘:off’
      A string representing the ‘off’ state.  By default the string
      ‘off’.
+
 ‘:on-glyph’
      Name of a glyph to be used instead of the ‘:on’ text string, on
      emacsen that supports this.
+
 ‘:off-glyph’
      Name of a glyph to be used instead of the ‘:off’ text string, on
      emacsen that supports this.
 
-5.12 The ‘checkbox’ Widget
-==========================
+‘:value-create’
+     A function for creating the widget’s value, according to its ‘:on’
+     or ‘:off’ state.
+
+‘:action’
+     Function to toggle the state of the widget.  After toggling, it
+     notifies itself.
+
+‘:match’
+     This widget matches anything.
+
+8.1.18 The ‘radio-button-toggle’ Widget
+---------------------------------------
+
+Syntax:
+
+     TYPE ::= (radio-button-toggle [KEYWORD ARGUMENT]...)
+
+   A toggle to use in the ‘radio’ widget.
+
+   It overrides the following properties:
+
+‘:button-prefix’
+     The empty string.
+
+‘:button-suffix’
+     The empty string.
+
+‘:on’
+     The string “(*)”, to represent the ‘on’ state.
+
+‘:off’
+     The string “( )”, to represent the ‘off’ state.
+
+‘:on-glyph’
+     The name of an image to represent the ‘on’ state.
+
+‘:off-glpyh’
+     The name of an image to represent the ‘off’ state.
+
+‘:format’
+     By default, it buttonizes its value.
+
+‘:notify’
+     A function to notify its parent.
 
-This widget has two possible states, ‘selected’ and ‘unselected’, which
-corresponds to a ‘t’ or ‘nil’ value.
+8.1.19 The ‘checkbox’ Widget
+----------------------------
 
-   Syntax:
+Syntax:
 
      TYPE ::= (checkbox [KEYWORD ARGUMENT]...)
 
-5.13 The ‘checklist’ Widget
-===========================
+   A widget to represent a toggle widget, with a checkbox.  Its super is
+the ‘toggle’ widget.
+
+   This widget has two possible states, ‘selected’ and ‘unselected’,
+which corresponds to a ‘t’ or ‘nil’ value, respectively.
+
+   It either overrides or adds the following properties:
+
+‘:button-prefix’
+     The empty string.
+
+‘:button-suffix’
+     The empty string.
+
+‘:format’
+     By default, buttonizes the value.
+
+‘:on’
+     By default, the string “[X]”.
+
+‘:off’
+     By default, the string “[ ]”.
+
+‘:on-glyph’
+     The name of the image to use when the state is ‘on’.
+
+‘:off-glyph’
+     The name of the image to use when the state is ‘off’.
+
+‘:action’
+     A function that toggles the checkbox, notifies the parents and in
+     the ‘on’ state, activates its siblings.
+
+8.1.20 The ‘checklist’ Widget
+-----------------------------
 
 Syntax:
 
      TYPE ::= (checklist [KEYWORD ARGUMENT]...  TYPE ... )
 
+   A widget to represent a multiplice choice.  Its super is the
+‘default’ widget.
+
    The TYPE arguments represent each checklist item.  The widget’s value
-will be a list containing the values of all checked TYPE arguments.  The
-checklist widget will match a list whose elements all match at least one
-of the specified TYPE arguments.
+will be a list containing the values of all checked TYPE arguments.
 
-   The following extra properties are recognized:
+   It either overrides or adds the following properties:
+
+‘:convert-widget’
+     As other composite widgets, a function that takes care of
+     converting each checklist item.
+
+‘:copy’
+     A function to copy each checklist item.
+
+‘:format’
+     By default, it inserts its value.
 
 ‘:entry-format’
      This string will be inserted for each entry in the list.  The
@@ -866,13 +1855,6 @@
      ‘%%’
           Insert a literal ‘%’.
 
-‘:greedy’
-     Usually a checklist will only match if the items are in the exact
-     sequence given in the specification.  By setting ‘: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.
-
 ‘:button-args’
      A list of keywords to pass to the checkboxes.  Useful for setting,
      e.g., the ‘:help-echo’ for each checkbox.
@@ -886,17 +1868,48 @@
 ‘:args’
      The list of types.
 
-5.14 The ‘editable-list’ Widget
-===============================
+‘:value-create’
+     The function that takes care of inserting all values.
+
+‘:value-get’
+     A function that returns all values of selected items.
+
+‘:validate’
+     A function that ensures all selected children are valid.
+
+‘:match’
+     The checklist widget will match a list whose elements all match at
+     least one of the specified TYPE arguments.
+
+‘:match-inline’
+     Like the ‘:match’ function, but taking into account the ‘:inline’
+     property.
+
+‘:greedy’
+     Usually a checklist will only match if the items are in the exact
+     sequence given in the specification.  By setting ‘: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.
+
+8.1.21 The ‘editable-list’ Widget
+---------------------------------
 
 Syntax:
 
      TYPE ::= (editable-list [KEYWORD ARGUMENT]... TYPE)
 
-   The value is a list, where each member represents one widget of type
-TYPE.
+   A widget that can hold a variable list of widgets of the same type,
+represented by TYPE.  Its super is the ‘default’ widget.
 
-   The following extra properties are recognized:
+   It either overrides or adds the following properties:
+
+‘:convert-widget’
+     As other composite widgets, a function that takes care of
+     converting each type in TYPE.
+
+‘:copy’
+     A function to copy the types given in TYPE.
 
 ‘:entry-format’
      This string will be inserted for each entry in the list.  The
@@ -905,9 +1918,9 @@
           This will be replaced with the buffer representation of the
           TYPE widget.
      ‘%i’
-          Insert the [INS] button.
+          Insert the [INS] button, a widget of type ‘insert-button’.
      ‘%d’
-          Insert the [DEL] button.
+          Insert the [DEL] button, a widget of type ‘delete-button’.
      ‘%%’
           Insert a literal ‘%’.
 
@@ -923,32 +1936,138 @@
 ‘:buttons’
      The widgets representing the insert and delete buttons.
 
+‘:format’
+     By default, insert its value and at the and adds an insert button.
+
+     This is useful so that new elements can be added to the list upon
+     user request.
+
+‘:format-handler’
+     A function that recognize the escape for inserting an insert
+     button.
+
+‘:offset’
+     By default, this widget has an offset of 12.
+
 ‘:children’
      The widgets representing the elements of the list.
 
 ‘:args’
      List whose CAR is the type of the list elements.
 
-5.15 The ‘group’ Widget
-=======================
+‘:insert-before’
+     Function to insert a new widget as a child of the ‘editable-list’
+     widget.
+
+     This function inserts a recently deleted child, if there is one.
+     That is useful, so that the user can move elements in a list
+     easily.  If there is not a recently deleted child, it inserts a
+     child with its default value.
+
+‘:delete-at’
+     Function to delete a child from the widget, and store it into the
+     ‘:last-deleted’ list, so that it can be reinserted when the
+     ‘:insert-before’ function executes.
+
+‘:value-create’
+     The function that takes care of inserting all values.
+
+‘:value-get’
+     Function that returns a list with the value of the child widgets.
+
+‘:validate’
+     This widget validates if all children validate.
 
-This widget simply group other widgets together.
+‘:match’
+     To match, the value must be a list and all the list members must
+     match the specified TYPE.
+
+‘:match-inline’
+     Like the ‘:match’ function, but taking into account inline values
+     and widgets.
 
-   Syntax:
+8.1.22 The ‘group’ Widget
+-------------------------
+
+Syntax:
 
      TYPE ::= (group [KEYWORD ARGUMENT]... TYPE...)
 
-   The value is a list, with one member for each TYPE.
+   A widget to group other widgets.  Its super is the ‘default’ widget.
 
-6 Sexp Types
-************
+   Its value is a list, with one member for each TYPE.
+
+   It overrides the following properties:
+
+‘:convert-widget’
+     As other composite widgets, a function that takes care of
+     converting each widget in TYPE.
+
+‘:copy’
+     A function to copy the types given in TYPE.
+
+‘:format’
+     By default, displays a newline character and its value.
+
+‘:value-create’
+     A function to create each of its components.
+
+‘:value-get’
+     The same function used by the ‘editable-list’ widget.
+
+‘:default-get’
+     A function that returns a list whose members are the default values
+     of each widget it groups.
+
+‘:validate’
+     This widget validates if all of its children validate.
+
+‘:match’
+     This widget matches a value that matches each of its components.
+
+‘:match-inline’
+     As ‘:match’, but taking into account widgets and values that are
+     inline.
+
+8.1.23 The ‘documentation-string’ Widget
+----------------------------------------
+
+Syntax:
+
+     TYPE ::= (documentation-string [KEYWORD ARGUMENT]... VALUE)
+
+   A widget to represent a documentation string.  Its super is the
+‘item’ widget.
+
+   It either overrides or adds the following properties:
+
+‘:format’
+     By default, insert its value.
+
+‘:value-create’
+     Function to insert a documentation string, possibly hiding part of
+     the documentation if its large.
+
+     To show or hide the rest of the documentation, uses a ‘visibility’
+     widget.
+
+‘:action’
+     Function to toggle showing the documentation upon an event.
+
+‘:visibility-widget’
+     A symbol, the type of the widget to use for the visibility widget.
+
+     This is, by default, the symbol ‘visibility’.
+
+8.2 Sexp Types
+==============
 
 A number of widgets for editing “s-expressions” (Lisp types), sexp for
 short, are also available.  These basically fall in several categories
 described in this section.
 
-6.1 The Constant Widgets
-========================
+8.2.1 The Constant Widgets
+--------------------------
 
 The ‘const’ widget can contain any Lisp expression, but the user is
 prohibited from editing it, which is mainly useful as a component of one
@@ -958,18 +2077,24 @@
 
      TYPE ::= (const [KEYWORD ARGUMENT]...  [ VALUE ])
 
-   The VALUE, if present, is used to initialize the ‘:value’ property
-and can be any s-expression.
+   Its super is the ‘item’ widget.  The VALUE, if present, is used to
+initialize the ‘:value’ property and can be any s-expression.
 
  -- Widget: const
      This will display any valid s-expression in an immutable part of
      the buffer.
 
+     It overrides the ‘:prompt-value’ function, to avoid prompting and
+     just return the widget’s value.
+
    There are two variations of the ‘const’ widget, namely
 ‘variable-item’ and ‘function-item’.  These should contain a symbol with
-a variable or function binding.  The major difference from the ‘const’
-widget is that they will allow the user to see the variable or function
-documentation for the symbol.
+a variable or function binding, respectively.  The major difference from
+the ‘const’ widget is that they will allow the user to see the variable
+or function documentation for the symbol.
+
+   This is accomplished via using the ‘%h’ format escape, and adding an
+appropiate ‘:documentation-property’ function for each widget.
 
  -- Widget: variable-item
      An immutable symbol that is bound as a variable.
@@ -977,8 +2102,8 @@
  -- Widget: function-item
      An immutable symbol that is bound as a function.
 
-6.2 Generic Sexp Widget
-=======================
+8.2.2 Generic Sexp Widget
+-------------------------
 
 The ‘sexp’ widget can contain any Lisp expression, and allows the user
 to edit it inline in the buffer.
@@ -988,74 +2113,165 @@
      TYPE ::= (sexp [KEYWORD ARGUMENT]...  [ VALUE ])
 
  -- Widget: sexp
-     This will allow you to edit any valid s-expression in an editable
-     buffer field.
+     This widget represents an editable field that’s useful to edit any
+     valid s-expression.
 
      The ‘sexp’ widget takes the same keyword arguments as the
      ‘editable-field’ widget.  *Note editable-field::.
 
-6.3 Atomic Sexp Widgets
-=======================
+     Its default value is ‘nil’.
+
+ -- Widget: restricted-sexp
+     A widget to edit Lisp expressions restricted to certain values or
+     types.  Its super is the ‘sexp’ widget.
+
+     It works just like the sexp widget, but it overrides the ‘:match’
+     function to match for certain values.  To use this widget, either
+     you must define a ‘:match’ function or give a ‘:match-alternatives’
+     property.  The ‘:match-alternatives’ property holds a list of
+     predicate functions to call when checking if a given value matches
+     the widget.  Each predicate function will be called with one
+     argument, the value to be matched, and should return non-‘nil’ on
+     success.
+
+     As an example, the ‘integer’ widget overrides ‘:match-alternatives’
+     to ‘(integerp)’.
+
+8.2.3 Atomic Sexp 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.
+is a composite type.  You can edit the value of an atom with the widgets
+described in this section.
 
-   The syntax for all the atoms are:
+   The syntax for all the atoms is:
 
      TYPE ::= (CONSTRUCT [KEYWORD ARGUMENT]...  [ VALUE ])
 
    The VALUE, if present, is used to initialize the ‘:value’ property
-and must be an expression of the same type as the widget.  That is, the
-string widget can only be initialized with a string.
+and must be an expression of the same type as the widget.  That is, for
+example, the string widget can only be initialized with a string.
 
    All the atom widgets take the same keyword arguments as the
 ‘editable-field’ widget.  *Note editable-field::.
 
  -- Widget: string
-     Allows you to edit a string in an editable field.
+     An editable field widget that can represent any Lisp string.
+
+     It offers completion via the ispell library and the ‘:complete’
+     property.
 
  -- Widget: regexp
-     Allows you to edit a regular expression in an editable field.
+     An editable field widget that can represent a regular expression.
+
+     Overrides the ‘:match’ and the ‘:validate’ properties to check that
+     the value is a valid regexp.
 
  -- Widget: character
-     Allows you to enter a character in an editable field.
+     An editable field widget that can represent a character.
+
+     The character widget represents some characters (like the newline
+     character) in a special manner, to make it easier for the user to
+     see what’s the content of the character field.
 
  -- Widget: file
-     Allows you to edit a file name in an editable field.
+     A widget for editing file names.
 
      Keywords:
+     ‘:completions’
+          Offers file name completion to the user.
+
+     ‘:prompt-value’
+          A function to read a file name from the minibuffer.
+
      ‘:must-match’
-          If this is set to non-‘nil’, only existing file names will be
-          allowed in the minibuffer.
+          If this is set to non-‘nil’, only existing file names are
+          allowed when prompting for a value in the minibuffer.
+
+     ‘:match’
+          The widget matches if the value is a string, and the file
+          whose name is that string is an existing file, or if
+          ‘:must-match’ is ‘nil’.
+
+     ‘:validate’
+          The widget is valid if its value matches.
 
  -- Widget: directory
-     Allows you to edit a directory name in an editable field.  Similar
-     to the ‘file’ widget.
+     A widget for editing directory names.
+
+     Its super is the ‘file’ widget, and it overrides the ‘:completions’
+     property, to offer completions only for directories.
 
  -- Widget: symbol
-     Allows you to edit a Lisp symbol in an editable field.
+     A widget for editing a Lisp symbol.
+
+     Its value by default is ‘nil’.
 
  -- Widget: function
-     Allows you to edit a lambda expression, or a function name with
-     completion.
+     A widget for editing a lambda expression, or a function name,
+     offering completion.  Its super is the ‘restricted-sexp’ widget.
 
  -- Widget: variable
-     Allows you to edit a variable name, with completion.
+     A widget for editing variable names, offering completion.  Its
+     super is the ‘symbol’ widget.
 
  -- Widget: integer
-     Allows you to edit an integer in an editable field.
+     A widget for editing integers in an editable field.  Its super is
+     the ‘restricted-sexp’ widget.
+
+     It has a default ‘:value’ of 0.
+
+ -- Widget: natnum
+     A widget for editing non-negative integers.  Its super is the
+     ‘restricted-sexp’ widget.
+
+     It has a default ‘:value’ of 0.
+
+ -- Widget: float
+     A widget for editing a floating point number.  Its super is the
+     ‘restricted-sexp’ widget.
+
+     It has a default ‘:value’ of 0.0.
 
  -- Widget: number
-     Allows you to edit a number in an editable field.
+     A widget for editing a number, either floating point or integer.
+     Its super is the ‘restricted-sexp’ widget.
+
+     It has a default ‘:value’ of 0.0.
 
  -- Widget: boolean
-     Allows you to edit a boolean.  In Lisp this means a variable which
-     is either ‘nil’ meaning false, or non-‘nil’ meaning true.
+     A widget for editing a boolean value.  Its super is the ‘toggle’
+     widget.
+
+     Its value may be ‘nil’, meaning false, or non-‘nil’, meaning true.
+
+ -- Widget: color
+     A widget to edit a color name.
+
+     In addition, shows a sample that shows the selected color, if any.
+
+ -- Widget: other
+     A widget useful as the last item in a ‘choice’ widget, since it
+     matches any value.
+
+     Its super is the ‘sexp’ widget, and its ‘:value’ is ‘other’, by
+     default.
+
+ -- Widget: coding-system
+     A widget that can represent a coding system name, offering
+     completions.  *Note (elisp)Coding Systems::.  Its super is the
+     ‘symbol’ widget.
+
+     It has a default value of ‘undecided’.
+
+ -- Widget: key
+     A widget to represent a key sequence.
+
+     It uses a special keymap as the ‘:keymap’.
 
-6.4 Composite Sexp Widgets
-==========================
+8.2.4 Composite Sexp Widgets
+----------------------------
 
 The syntax for the composite widget construct is:
 
@@ -1065,34 +2281,50 @@
 be displayed in the buffer, and will be editable by the user.
 
  -- Widget: cons
+     A widget to edit cons-cell values.  Its super is the ‘group’
+     widget.
+
      The value of a ‘cons’ widget must be a cons-cell whose CAR and CDR
      have two specified types.  It uses this syntax:
 
           TYPE ::= (cons [KEYWORD ARGUMENT]...  CAR-TYPE CDR-TYPE)
 
  -- Widget: choice
-     The value matched by a ‘choice’ widget must have one of a fixed set
-     of types.  The widget’s syntax is as follows:
+     A widget to hold a value of one of a fixed set of types.  Its super
+     is the ‘menu-choice’ widget.
+
+     The widget’s syntax is as follows:
 
           TYPE ::= (choice [KEYWORD ARGUMENT]...  TYPE ... )
 
      The value of a ‘choice’ widget can be anything that matches any of
      the TYPES.
 
+     This widget only displays the widget that corresponds to the
+     current choice.
+
+ -- Widget: radio
+     A widget to hold a value of one of a fixed set of options.  Its
+     super is the ‘radio-button-choice’ widget.
+
  -- Widget: list
+     A widget to edit a list value.  Its super is the ‘group’ widget.
+
      The value of a ‘list’ widget must be a list whose element types
      match the specified component types:
 
           TYPE ::= (list [KEYWORD ARGUMENT]...  COMPONENT-TYPE...)
 
-     Thus, ‘(list string number)’ matches lists of two elements, the
-     first being a string and the second being a number.
+     Thus, for example, ‘(list string number)’ matches lists of two
+     elements, the first being a string and the second being a number.
 
  -- Widget: vector
+     A widget to edit a vector value.  Its super is the ‘group’ widget.
+
      The ‘vector’ widget is like the ‘list’ widget but matches vectors
-     instead of lists.  Thus, ‘(vector string number)’ matches vectors
-     of two elements, the first being a string and the second being a
-     number.
+     instead of lists.  Thus, for example, ‘(vector string number)’
+     matches vectors of two elements, the first being a string and the
+     second being a number.
 
    The above suffice for specifying fixed size lists and vectors.  To
 get variable length lists and vectors, you can use a ‘choice’, ‘set’, or
@@ -1117,9 +2349,13 @@
 to explain it here, I’ll just suggest you meditate over it for a while.
 
  -- Widget: set
-     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:
+     A widget to hold a list of members from a fixed set.  Its super is
+     the ‘checklist’ widget.
+
+     Its value is a list where the elements all belong to a given set.
+     The order of elements of the list is not significant.
+
+     Here’s the syntax:
 
           TYPE ::= (set [KEYWORD ARGUMENT]...  PERMITTED-ELEMENT ... )
 
@@ -1128,89 +2364,47 @@
 
  -- Widget: repeat
      Specifies a list of any number of elements that fit a certain type.
+     Its super is the ‘editable-list’ widget.
 
           TYPE ::= (repeat [KEYWORD ARGUMENT]...  TYPE)
 
-7 Properties
-************
-
-You can examine or set the value of a widget by using the widget object
-that was returned by ‘widget-create’.
-
- -- Function: widget-value widget
-     Return the current value contained in WIDGET.  It is an error to
-     call this function on an uninitialized widget.
-
- -- Function: widget-value-set widget value
-     Set the value contained in WIDGET to VALUE.  It is an error to call
-     this function with an invalid VALUE.
+ -- Widget: plist
+     A widget to edit property lists.  Its super is the ‘list’ widget.
 
-   *Important:* You _must_ call ‘widget-setup’ after modifying the value
-of a widget before the user is allowed to edit the widget again.  It is
-enough to call ‘widget-setup’ once if you modify multiple widgets.  This
-is currently only necessary if the widget contains an editing field, but
-may be necessary for other widgets in the future.
+     It recognizes the following properties:
 
-   If your application needs to associate some information with the
-widget objects, for example a reference to the item being edited, it can
-be done with ‘widget-put’ and ‘widget-get’.  The property names must
-begin with a ‘:’.
+     ‘:options’
+          A given set of recommended key-value values for the ‘plist’
+          widget.  Each option shows up as a checklist item.
 
- -- Function: widget-put widget property value
-     In WIDGET set PROPERTY to VALUE.  PROPERTY should be a symbol,
-     while VALUE can be anything.
+     ‘:key-type’
+          The widget type to use for the plist keys.  By default, it
+          uses the ‘symbol’ widget.
 
- -- Function: widget-get widget property
-     In WIDGET return the value for PROPERTY.  PROPERTY should be a
-     symbol, the value is what was last set by ‘widget-put’ for
-     PROPERTY.
+     ‘:value-type’
+          The widget type to use for the plist values.  By default, it
+          uses the ‘sexp’ widget.
 
- -- Function: widget-member widget property
-     Non-‘nil’ if WIDGET has a value (even ‘nil’) for property PROPERTY.
+ -- Widget: alist
+     A widget to edit association lists.  Its super is the ‘list’
+     widget.
 
- -- Function: widget-apply widget property &rest args
-     Apply the value of PROPERTY to WIDGET, passing ARGS as additional
-     arguments to the function.  Return the result of that function
-     call.
+     It recognizes the same properties that the ‘plist’ widget, with the
+     difference that the ‘:key-type’ uses by default a ‘sexp’ widget.
 
-   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.
+   Most composite widgets do not allow for recursion.  That is, none of
+the contained widgets may be of the same type that is currently being
+defined.  To allow for this kind of widgets, there’s the ‘lazy’ widget.
 
- -- Function: widget-type widget
-     Return the name of WIDGET, a symbol.
+ -- Widget: lazy
+     A base widget for recursive data structures.  Its super is the
+     ‘default’ 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:
-
-     ;; Examine if WIDGET is active or not.
-     (if (widget-apply WIDGET :active)
-         (message "Widget is active.")
-       (message "Widget is inactive.")
-
-     ;; Make WIDGET inactive.
-     (widget-apply WIDGET :deactivate)
-
-     ;; Make WIDGET active.
-     (widget-apply WIDGET :activate)
-
-   A widget is inactive if it, or any of its ancestors (found by
-following the ‘:parent’ link), have been deactivated.  To make sure a
-widget is really active, you must therefore activate both it and all its
-ancestors.
-
-     (while widget
-       (widget-apply widget :activate)
-       (setq widget (widget-get widget :parent)))
-
-   You can check if a widget has been made inactive by examining the
-value of the ‘:inactive’ keyword.  If this is non-‘nil’, the widget
-itself has been deactivated.  This is different from using the ‘:active’
-keyword, in that the latter tells you if the widget *or* any of its
-ancestors have been deactivated.  Do not attempt to set the ‘:inactive’
-keyword directly.  Use the ‘:activate’ ‘:deactivate’ keywords instead.
+     When instantiated, it contains a single inferior widget of the
+     widget type specified in the ‘:type’ property.  Its value is the
+     same as the value of this inferior widget.
 
-8 Defining New Widgets
+9 Defining New Widgets
 **********************
 
 You can define specialized widgets with ‘define-widget’.  It allows you
@@ -1218,15 +2412,24 @@
 component widgets and new default values for the keyword arguments.
 
  -- Function: define-widget name class doc &rest args
-     Define a new widget type named NAME from ‘class’.
+     Define a new widget type named NAME that derives from CLASS.
 
-     NAME and class should both be symbols, ‘class’ should be one of the
-     existing widget types.
+     NAME and CLASS should both be symbols, and CLASS should be one of
+     the existing widget types.
 
      The third argument DOC is a documentation string for the widget.
 
-     After the new widget has been defined, the following two calls will
-     create identical widgets:
+     ARGS should be key-value pairs, overriding keyword values of CLASS,
+     or adding new recognized keywords for NAME.
+
+     Usually, you’ll want to derive from an existing widget type, like
+     the ‘editable-field’ widget, or the ‘default’ widget, but it’s also
+     possible to derive from nothing, by passing a value of ‘nil’ as
+     CLASS.  Note that if you do this, you’re entirely responsible for
+     defining a whole new default behavior for your widgets.
+
+     After using this function, the following two calls will create
+     identical widgets:
 
         •      (widget-create NAME)
 
@@ -1239,147 +2442,61 @@
    If you only want to specify defaults for keywords with no complex
 conversions, you can use ‘identity’ as your conversion function.
 
-   The following additional keyword arguments are useful when defining
-new widgets:
+   When defining new widgets, the ‘:convert-widget’ property might be
+useful:
+
 ‘: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 widget type.  When a widget is created, this function is
-     called for the widget type and all the widget’s parent types, most
-     derived first.
-
-     The following predefined functions can be used here:
-
-      -- Function: widget-types-convert-widget widget
-          Convert ‘:args’ as widget types in WIDGET.
-
-      -- Function: widget-value-convert-widget widget
-          Initialize ‘:value’ from ‘:args’ in WIDGET.
-
-‘:copy’
-     Function to deep copy a widget type.  It takes a shallow copy of
-     the widget type as an argument (made by ‘copy-sequence’), and
-     returns a deep copy.  The purpose of this is to avoid having
-     different instances of combined widgets share nested attributes.
-
-     The following predefined functions can be used here:
-
-      -- Function: widget-types-copy widget
-          Copy ‘:args’ as widget types in WIDGET.
-
-‘: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 internal value.  The function is called on the present ‘:value’
-     when the widget is created, and on any value set later with
-     ‘widget-value-set’.
+     type.
 
-‘: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 external value.
-
-‘: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.
-
-‘:delete’
-     Function to delete a widget.  The function takes one argument, a
-     widget, and should remove all traces of the widget from the buffer.
-
-     The default value is:
-
-      -- Function: widget-default-delete widget
-          Remove WIDGET from the buffer.  Delete all ‘:children’ and
-          ‘:buttons’ in WIDGET.
-
-     In most cases you should not change this value, but instead use
-     ‘:value-delete’ to make any additional cleanup.
-
-‘:value-create’
-     Function to expand the ‘%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.
-
-     Nested widgets should be listed in ‘:children’ or ‘:buttons’ to
-     make sure they are automatically deleted.
-
-‘: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 remove the text, but it should release markers and
-     delete nested widgets if these are not listed in ‘:children’ or
-     ‘:buttons’.
-
-‘:value-get’
-     Function to extract the value of a widget, as it is displayed in
-     the buffer.
+     It takes a widget type as an argument, and returns the converted
+     widget type.  When a widget is created, this function is called for
+     the widget type and all the widget’s parent types, most derived
+     first.
 
-     The following predefined function can be used here:
+     The predefined functions ‘widget-types-convert-widget’ and
+     ‘widget-value-convert-widget’ can be used here.
 
-      -- Function: widget-value-value-get widget
-          Return the ‘:value’ property of WIDGET.
-
-‘:format-handler’
-     Function to handle unknown ‘%’ escapes in the format string.  It
-     will be called with the widget and the character that follows the
-     ‘%’ as arguments.  You can set this to allow your widget to handle
-     non-standard escapes.
-
-     You should end up calling ‘widget-default-format-handler’ to handle
-     unknown escape sequences, which will handle the ‘%h’ and any future
-     escape sequences, as well as give an error for unknown escapes.
-
-‘:action’
-     Function to handle user initiated events.  By default, ‘:notify’
-     the parent.
+10 Inspecting Widgets
+*********************
 
-     The following predefined function can be used here:
+There is a separate package to browse widgets, in ‘wid-browse.el’.  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.
 
-      -- Function: widget-parent-action widget &optional event
-          Tell ‘:parent’ of WIDGET to handle the ‘:action’.  Optional
-          EVENT is the event that triggered the action.
+ -- Command: widget-browse WIDGET
+     Create a widget browser for WIDGET.
 
-‘:prompt-value’
-     Function to prompt for a value in the minibuffer.  The function
-     should take four arguments, WIDGET, PROMPT, VALUE, and UNBOUND and
-     should return a value for widget entered by the user.  PROMPT is
-     the prompt to use.  VALUE is the default value to use, unless
-     UNBOUND is non-‘nil’, in which case there is no default value.  The
-     function should read the value using the method most natural for
-     this widget, and does not have to check that it matches.
+     When called interactively, prompt for WIDGET.
 
-   If you want to define a new widget from scratch, use the ‘default’
-widget as its base.
+ -- Command: widget-browse-other-window WIDGET
+     Create a widget browser for WIDGET and show it in another window.
 
- -- Widget: default
-     Widget used as a base for other widgets.
+     When called interactively, prompt for WIDGET.
 
-     It provides most of the functionality that is referred to as “by
-     default” in this text.
+ -- Command: widget-browse-at POS
+     Create a widget browser for the widget at POS.
 
-9 Widget Browser
-****************
+     When called interactively, use the position of point.
 
-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.
+   In addition, there’s a function to describe the widget at point.
 
- -- Command: widget-browse WIDGET
-     Create a widget browser for WIDGET.  When called interactively,
-     prompt for WIDGET.
+ -- Command: widget-describe &optional widget-or-pos
+     Describe the widget at point.
 
- -- Command: widget-browse-other-window WIDGET
-     Create a widget browser for WIDGET and show it in another window.
-     When called interactively, prompt for WIDGET.
+     When called from Lisp, WIDGET-OR-POS might be the widget to
+     describe or a buffer position where a widget is present.  If
+     WIDGET-OR-POS is ‘nil’, the widget to describe is the widget at
+     point.
 
- -- Command: widget-browse-at POS
-     Create a widget browser for the widget at POS.  When called
-     interactively, use the position of point.
+     This command sets up a help buffer for providing information about
+     the widget, mainly its ‘:action’ and ‘:mouse-down-action’
+     functions, and provides links to describe it in more detail using
+     the ‘widget-browse’ commands described above.
 
-10 Widget Minor Mode
+11 Widget Minor Mode
 ********************
 
 There is a minor mode for manipulating widgets in major modes that don’t
@@ -1393,16 +2510,26 @@
  -- Variable: widget-minor-mode-keymap
      Keymap used in ‘widget-minor-mode’.
 
-11 Utilities
+12 Utilities
 ************
 
+Here we describe some utility functions that don’t really have a place
+earlier in this manual.
+
  -- Function: widget-prompt-value widget prompt [ value unbound ]
      Prompt for a value matching WIDGET, using PROMPT.  The current
      value is assumed to be VALUE, unless UNBOUND is non-‘nil’.
 
+     Converts WIDGET before prompting, and for prompting it uses the
+     ‘:prompt-value’ function.  This function returns the user “answer”,
+     and it’s an error if that answer doesn’t match the widget, as with
+     the ‘:match’ function.
+
+     If the answer matches the widget, returns the answer.
+
  -- Function: widget-get-sibling widget
-     Get the item which WIDGET is assumed to toggle.  This is only
-     meaningful for radio buttons or checkboxes in a list.
+     Get the item which WIDGET should toggle.  This is only meaningful
+     for radio buttons or checkboxes in a list.
 
  -- Function: widget-choose title items &optional event
      Prompt the user to choose an item from a list of options.
@@ -1424,7 +2551,124 @@
      simplified format), then the return value is the VALUE of the
      chosen element.
 
-12 Wishlist
+ -- Function: widget-image-find image
+     Create a graphical button from IMAGE, an image or a file name sans
+     extension.
+
+     If IMAGE is a file name, the file should be in
+     ‘widget-image-directory’, or in a place where ‘find-image’ will
+     find it.
+
+ -- Function: widget-image-insert widget tag image
+     As part of WIDGET, insert the text TAG or, if supported, the image
+     IMAGE.
+
+     IMAGE should be as described in ‘widget-image-find’.
+
+ -- Function: widget-echo-help pos
+     Display help-echo text for the widget at POS.
+
+     Uses the value of ‘:help-echo’.  If it is a function, it calls it
+     to get a string.  Otherwise, it ‘eval’s it.
+
+13 Customization
+****************
+
+This chapter is about the customization options for the Widget library,
+for the end user.
+
+ -- Face: widget-field-face
+     Face used for other editing fields.
+
+ -- Face: widget-button-face
+     Face used for buttons.
+
+ -- User Option: widget-mouse-face
+     Face used for highlighting a button when the mouse pointer moves
+     across it.
+
+     The default value is ‘highlight’.
+
+ -- User Option: widget-image-directory
+     Directory where Widget should look for images.
+
+     Widget will look here for a file with the same name as specified
+     for the image, with either a ‘.xpm’ (if supported) or ‘.xbm’
+     extension.
+
+ -- User Option: widget-image-enable
+     If non-‘nil’, allow images to appear on displays where they are
+     supported.
+
+ -- User Option: widget-image-conversion
+     An alist to convert symbols from image formats to file name
+     suffixes.
+
+     Each element is a cons cell (FORMAT .  SUFFIX), where FORMAT is a
+     symbol that represents an image format and SUFFIX is its
+     correspondent suffix.
+
+ -- User Option: widget-button-prefix
+     String to prefix buttons.
+
+ -- User Option: widget-button-suffix
+     String to suffix buttons.
+
+ -- User Option: widget-push-button-prefix
+     String to prefix push buttons.
+
+ -- User Option: widget-push-button-suffix
+     String to suffix push buttons.
+
+ -- User Option: widget-link-prefix
+     String to prefix links.
+
+ -- User Option: widget-link-suffix
+     String to suffix links.
+
+ -- User Option: widget-choice-toggle
+     If non-‘nil’, toggle when there are just two options.
+
+     By default, its value is ‘nil’.
+
+ -- User Option: widget-documentation-links
+     If non-‘nil’, add hyperlinks to documentation strings.
+
+ -- User Option: widget-documentation-link-regexp
+     A regexp that matches potential links in documentation strings.
+     The link itself should match to the first group.
+
+ -- User Option: widget-documentation-link-p
+     A predicate function to test if a string is useful as a link.  The
+     function is called with one argument, a string, and should return
+     non-‘nil’ if there should be a link for that string.
+
+     By default, the value is ‘intern-soft’.
+
+ -- User Option: widget-documentation-link-type
+     A symbol that represents a widget type to use for links in
+     documentation strings.
+
+     By default, the value is ‘documentation-link’.
+
+ -- User Option: widget-menu-max-size
+     Maximum size for a popup menu.  By default, its value is 40.
+
+     If a function ask you to choose from a menu that is larger than
+     this value, it will use the minibuffer.
+
+ -- User Option: widget-menu-max-shortcuts
+     Largest number of items for which it works to choose one with a
+     character.
+
+     For a larger number, use the minibuffer.
+
+ -- User Option: widget-menu-minibuffer-flag
+     Whether to use the minibuffer to ask for a choice.
+
+     If ‘nil’, the default, read a single character.
+
+14 Wishlist
 ***********
 
    • It should be possible to add or remove items from a list with ‘C-k’
@@ -1449,12 +2693,6 @@
 
    • Find a way to make glyphs look inactive.
 
-   • Add ‘property-list’ widget.
-
-   • Add ‘association-list’ widget.
-
-   • Add ‘key-binding’ widget.
-
    • Add ‘widget’ widget for editing widget specifications.
 
    • Find clean way to implement variable length list.  See
@@ -1951,229 +3189,318 @@
 
 * Menu:
 
-* action keyword:                        Defining New Widgets.
-                                                             (line 1333)
-* activate a widget:                     Widget Properties.  (line 1181)
-* active widget:                         Widget Properties.  (line 1181)
-* append-button-args keyword:            editable-list.      (line  919)
-* args keyword:                          menu-choice.        (line  731)
+* action keyword:                        Widget Gallery.     (line 1124)
+* activate a widget:                     Widget Gallery.     (line 1083)
+* activate keyword:                      Widget Gallery.     (line 1116)
+* active keyword:                        Widget Gallery.     (line 1077)
+* active widget:                         Widget Gallery.     (line 1083)
+* alist:                                 composite.          (line 2387)
+* append-button-args keyword:            editable-list.      (line 1932)
+* args keyword:                          menu-choice.        (line 1538)
 * args keyword <1>:                      radio-button-choice.
-                                                             (line  771)
-* args keyword <2>:                      checklist.          (line  885)
-* args keyword <3>:                      editable-list.      (line  928)
-* atomic sexp widget:                    atoms.              (line  999)
-* basic widgets:                         Introduction.       (line   63)
-* boolean:                               atoms.              (line 1052)
-* browse-url-browser-function, and url-link widget: url-link.
-                                                             (line  629)
-* button widgets:                        User Interface.     (line  200)
+                                                             (line 1639)
+* args keyword <2>:                      checklist.          (line 1867)
+* args keyword <3>:                      editable-list.      (line 1954)
+* atomic sexp widget:                    atoms.              (line 2142)
+* basic widgets:                         Introduction.       (line   75)
+* boolean:                               atoms.              (line 2242)
+* button widgets:                        User Interface.     (line  202)
 * button-args keyword:                   radio-button-choice.
-                                                             (line  758)
-* button-args keyword <1>:               checklist.          (line  875)
-* button-face keyword:                   Basic Types.        (line  486)
-* button-prefix keyword:                 Basic Types.        (line  489)
-* button-suffix keyword:                 Basic Types.        (line  489)
+                                                             (line 1626)
+* button-args keyword <1>:               checklist.          (line 1857)
+* button-face keyword:                   Widget Gallery.     (line  915)
+* button-face-get keyword:               Widget Gallery.     (line 1050)
+* button-prefix keyword:                 Widget Gallery.     (line  918)
+* button-suffix keyword:                 Widget Gallery.     (line  918)
 * buttons keyword:                       radio-button-choice.
-                                                             (line  762)
-* buttons keyword <1>:                   checklist.          (line  879)
-* buttons keyword <2>:                   editable-list.      (line  922)
-* case-fold keyword:                     menu-choice.        (line  720)
-* character:                             atoms.              (line 1021)
-* checkbox widget:                       checkbox.           (line  837)
-* checklist widget:                      checklist.          (line  847)
-* children keyword:                      menu-choice.        (line  724)
+                                                             (line 1630)
+* buttons keyword <1>:                   checklist.          (line 1861)
+* buttons keyword <2>:                   editable-list.      (line 1935)
+* case-fold keyword:                     menu-choice.        (line 1525)
+* character:                             atoms.              (line 2170)
+* checkbox widget:                       checkbox.           (line 1785)
+* checklist widget:                      checklist.          (line 1825)
+* children keyword:                      menu-choice.        (line 1531)
 * children keyword <1>:                  radio-button-choice.
-                                                             (line  765)
-* children keyword <2>:                  checklist.          (line  882)
-* children keyword <3>:                  editable-list.      (line  925)
-* choice:                                composite.          (line 1072)
-* choice keyword:                        menu-choice.        (line  728)
+                                                             (line 1633)
+* children keyword <2>:                  checklist.          (line 1864)
+* children keyword <3>:                  editable-list.      (line 1951)
+* choice:                                composite.          (line 2291)
+* choice keyword:                        menu-choice.        (line 1535)
 * choice keyword <1>:                    radio-button-choice.
-                                                             (line  768)
-* choice-item widget:                    choice-item.        (line  800)
-* composite sexp widgets:                composite.          (line 1059)
-* cons:                                  composite.          (line 1066)
-* const:                                 constants.          (line  963)
-* constant widgets:                      constants.          (line  952)
+                                                             (line 1636)
+* choice-item widget:                    choice-item.        (line 1683)
+* coding-system:                         atoms.              (line 2260)
+* color:                                 atoms.              (line 2248)
+* completions-function keyword:          Widget Gallery.     (line 1028)
+* composite sexp widgets:                composite.          (line 2275)
+* cons:                                  composite.          (line 2282)
+* const:                                 constants.          (line 2082)
+* constant widgets:                      constants.          (line 2071)
 * convert-widget keyword:                Defining New Widgets.
-                                                             (line 1243)
-* copy keyword:                          Defining New Widgets.
-                                                             (line 1258)
-* create keyword:                        Defining New Widgets.
-                                                             (line 1281)
-* deactivate a widget:                   Widget Properties.  (line 1181)
-* default:                               Defining New Widgets.
-                                                             (line 1355)
+                                                             (line 2447)
+* copy keyword:                          Widget Gallery.     (line 1067)
+* create keyword:                        Widget Gallery.     (line  782)
+* deactivate a widget:                   Widget Gallery.     (line 1083)
+* deactivate keyword:                    Widget Gallery.     (line 1120)
+* default:                               Widget Gallery.     (line  773)
+* default-get keyword:                   Widget Gallery.     (line  869)
 * define-widget:                         Defining New Widgets.
-                                                             (line 1219)
+                                                             (line 2413)
 * defining new widgets:                  Defining New Widgets.
-                                                             (line 1215)
-* delete keyword:                        Defining New Widgets.
-                                                             (line 1286)
-* delete-button-args keyword:            editable-list.      (line  916)
-* directory:                             atoms.              (line 1032)
-* doc keyword:                           Basic Types.        (line  503)
-* editable-field widget:                 editable-field.     (line  663)
-* editable-list widget:                  editable-list.      (line  891)
-* embedded buttons:                      User Interface.     (line  227)
+                                                             (line 2409)
+* delete keyword:                        Widget Gallery.     (line  792)
+* delete-button-args keyword:            editable-list.      (line 1929)
+* directory:                             atoms.              (line 2199)
+* doc keyword:                           Widget Gallery.     (line  937)
+* documentation-string widget:           documentation-string.
+                                                             (line 2034)
+* editable-field widget:                 editable-field.     (line 1378)
+* editable-list widget:                  editable-list.      (line 1897)
+* emacs-commentary-link widget:          emacs-commentary-link.
+                                                             (line 1332)
+* emacs-library-link widget:             emacs-library-link. (line 1319)
+* embedded buttons:                      User Interface.     (line  219)
 * entry-format keyword:                  radio-button-choice.
-                                                             (line  748)
-* entry-format keyword <1>:              checklist.          (line  858)
-* entry-format keyword <2>:              editable-list.      (line  900)
+                                                             (line 1613)
+* entry-format keyword <1>:              checklist.          (line 1847)
+* entry-format keyword <2>:              editable-list.      (line 1913)
 * example of using widgets:              Programming Example.
-                                                             (line  273)
-* external format:                       Basic Types.        (line  422)
-* extra-offset keyword:                  Basic Types.        (line  533)
-* file:                                  atoms.              (line 1024)
-* follow-link keyword:                   Basic Types.        (line  521)
-* format keyword:                        Basic Types.        (line  435)
-* format-handler keyword:                Defining New Widgets.
-                                                             (line 1323)
-* function:                              atoms.              (line 1039)
-* function-item:                         constants.          (line  976)
-* generic sexp widget:                   generic.            (line  982)
-* greedy keyword:                        checklist.          (line  868)
-* group widget:                          group.              (line  934)
-* help-echo keyword:                     Basic Types.        (line  513)
-* inactive widget:                       Widget Properties.  (line 1181)
-* indent keyword:                        Basic Types.        (line  525)
-* info-link widget:                      info-link.          (line  635)
-* insert-button-args keyword:            editable-list.      (line  913)
-* integer:                               atoms.              (line 1046)
-* internal format:                       Basic Types.        (line  422)
-* item widget:                           item.               (line  789)
-* keymap keyword:                        editable-field.     (line  691)
-* keyword arguments:                     Basic Types.        (line  420)
-* link widget:                           link.               (line  607)
-* list:                                  composite.          (line 1081)
-* match keyword:                         Basic Types.        (line  554)
-* menu-choice widget:                    menu-choice.        (line  708)
-* menu-tag keyword:                      Basic Types.        (line  544)
-* menu-tag-get keyword:                  Basic Types.        (line  548)
-* mouse-2 (on button widgets):           User Interface.     (line  210)
-* must-match keyword:                    atoms.              (line 1028)
+                                                             (line  253)
+* external format:                       Widget Gallery.     (line  807)
+* extra-offset keyword:                  Widget Gallery.     (line  973)
+* face-link widget:                      face-link.          (line 1294)
+* file:                                  atoms.              (line 2177)
+* file-link widget:                      file-link.          (line 1306)
+* float:                                 atoms.              (line 2230)
+* follow-link keyword:                   Widget Gallery.     (line  956)
+* format keyword:                        Widget Gallery.     (line  874)
+* format-handler keyword:                Widget Gallery.     (line 1039)
+* function:                              atoms.              (line 2210)
+* function-item:                         constants.          (line 2101)
+* function-link widget:                  function-link.      (line 1269)
+* generic sexp widget:                   generic.            (line 2107)
+* greedy keyword:                        checklist.          (line 1887)
+* group widget:                          group.              (line 1991)
+* help-echo keyword:                     Widget Gallery.     (line  947)
+* inactive widget:                       Widget Gallery.     (line 1083)
+* indent keyword:                        Widget Gallery.     (line  960)
+* info-link widget:                      info-link.          (line 1256)
+* insert-button-args keyword:            editable-list.      (line 1926)
+* integer:                               atoms.              (line 2218)
+* internal format:                       Widget Gallery.     (line  807)
+* item widget:                           item.               (line 1168)
+* key:                                   atoms.              (line 2267)
+* keymap keyword:                        editable-field.     (line 1400)
+* keyword arguments:                     Widget Gallery.     (line  780)
+* lazy:                                  composite.          (line 2398)
+* link widget:                           link.               (line 1207)
+* list:                                  composite.          (line 2309)
+* match keyword:                         Widget Gallery.     (line  989)
+* menu-choice widget:                    menu-choice.        (line 1498)
+* menu-tag keyword:                      Widget Gallery.     (line  977)
+* menu-tag-get keyword:                  Widget Gallery.     (line  981)
+* mouse-2 (on button widgets):           Widgets and the Buffer.
+                                                             (line  740)
+* mouse-down-action keyword:             Widget Gallery.     (line 1131)
+* mouse-face-get keyword:                Widget Gallery.     (line 1058)
+* must-match keyword:                    atoms.              (line 2187)
+* natnum:                                atoms.              (line 2224)
 * new widgets:                           Defining New Widgets.
-                                                             (line 1215)
-* notify keyword:                        Basic Types.        (line  537)
-* number:                                atoms.              (line 1049)
-* off-glyph keyword:                     toggle.             (line  829)
-* offset keyword:                        Basic Types.        (line  529)
-* on-glyph keyword:                      toggle.             (line  826)
-* option field tag:                      User Interface.     (line  220)
-* parent keyword:                        Basic Types.        (line  585)
-* prompt-value keyword:                  Defining New Widgets.
-                                                             (line 1343)
-* properties of widgets:                 Widget Properties.  (line 1136)
-* push-button widget:                    push-button.        (line  645)
+                                                             (line 2409)
+* notify keyword:                        Widget Gallery.     (line 1137)
+* number:                                atoms.              (line 2236)
+* off-glyph keyword:                     toggle.             (line 1732)
+* offset keyword:                        Widget Gallery.     (line  969)
+* on-glyph keyword:                      toggle.             (line 1728)
+* option field tag:                      User Interface.     (line  212)
+* other:                                 atoms.              (line 2253)
+* parent keyword:                        Widget Gallery.     (line 1018)
+* plist:                                 composite.          (line 2370)
+* prompt-value keyword:                  Widget Gallery.     (line 1148)
+* push-button widget:                    push-button.        (line 1345)
+* radio:                                 composite.          (line 2305)
 * radio-button-choice widget:            radio-button-choice.
-                                                             (line  737)
-* regexp:                                atoms.              (line 1018)
-* repeat:                                composite.          (line 1128)
-* secret keyword:                        editable-field.     (line  681)
-* set:                                   composite.          (line 1118)
-* sexp:                                  generic.            (line  989)
-* sexp types:                            Sexp Types.         (line  945)
-* sibling-args keyword:                  Basic Types.        (line  589)
-* size keyword:                          editable-field.     (line  673)
-* string:                                atoms.              (line 1015)
-* symbol:                                atoms.              (line 1036)
-* tab-order keyword:                     Basic Types.        (line  570)
-* tag keyword:                           Basic Types.        (line  506)
-* tag-glyph keyword:                     Basic Types.        (line  509)
-* text widget:                           text.               (line  701)
-* todo:                                  Widget Wishlist.    (line 1429)
-* toggle widget:                         toggle.             (line  813)
-* url-link widget:                       url-link.           (line  625)
-* utility functions for widgets:         Utilities.          (line 1398)
-* valid-regexp keyword:                  editable-field.     (line  686)
-* validate keyword:                      Basic Types.        (line  559)
-* value keyword:                         Basic Types.        (line  422)
-* value-create keyword:                  Defining New Widgets.
-                                                             (line 1299)
-* value-delete keyword:                  Defining New Widgets.
-                                                             (line 1307)
-* value-face keyword:                    editable-field.     (line  677)
-* value-get keyword:                     Defining New Widgets.
-                                                             (line 1314)
-* value-to-external keyword:             Defining New Widgets.
-                                                             (line 1276)
-* value-to-internal keyword:             Defining New Widgets.
-                                                             (line 1269)
-* variable:                              atoms.              (line 1043)
-* variable-item:                         constants.          (line  973)
-* vector:                                composite.          (line 1090)
-* void keyword:                          menu-choice.        (line  716)
-* widget browser:                        Widget Browser.     (line 1364)
-* widget buttons:                        User Interface.     (line  200)
-* widget library, why use it:            Introduction.       (line  103)
-* widget minor mode:                     Widget Minor Mode.  (line 1384)
-* widget properties:                     Widget Properties.  (line 1136)
-* widget-apply:                          Widget Properties.  (line 1170)
-* widget-backward:                       User Interface.     (line  267)
-* widget-browse:                         Widget Browser.     (line 1369)
-* widget-browse-at:                      Widget Browser.     (line 1377)
-* widget-browse-other-window:            Widget Browser.     (line 1373)
-* widget-button-click:                   User Interface.     (line  211)
-* widget-button-click <1>:               Setting Up the Buffer.
-                                                             (line  399)
-* widget-button-face:                    User Interface.     (line  249)
-* widget-button-prefix:                  Basic Types.        (line  446)
-* widget-button-press:                   User Interface.     (line  205)
-* widget-button-press <1>:               Setting Up the Buffer.
+                                                             (line 1589)
+* radio-button-toggle widget:            radio-button-toggle.
+                                                             (line 1750)
+* regexp:                                atoms.              (line 2164)
+* repeat:                                composite.          (line 2364)
+* restricted-sexp:                       generic.            (line 2123)
+* secret keyword:                        editable-field.     (line 1424)
+* set:                                   composite.          (line 2350)
+* sexp:                                  generic.            (line 2114)
+* sexp types:                            Sexp Types.         (line 2064)
+* sibling-args keyword:                  Widget Gallery.     (line 1022)
+* size keyword:                          editable-field.     (line 1414)
+* string:                                atoms.              (line 2158)
+* symbol:                                atoms.              (line 2205)
+* tab-order keyword:                     Widget Gallery.     (line 1004)
+* tag keyword:                           Widget Gallery.     (line  940)
+* tag-glyph keyword:                     Widget Gallery.     (line  943)
+* text widget:                           text.               (line 1479)
+* todo:                                  Widget Wishlist.    (line 2673)
+* toggle widget:                         toggle.             (line 1705)
+* url-link widget:                       url-link.           (line 1244)
+* utility functions for widgets:         Utilities.          (line 2515)
+* valid-regexp keyword:                  editable-field.     (line 1431)
+* validate keyword:                      Widget Gallery.     (line  994)
+* value keyword:                         Widget Gallery.     (line  807)
+* value-create keyword:                  Widget Gallery.     (line  835)
+* value-delete keyword:                  Widget Gallery.     (line  841)
+* value-face keyword:                    editable-field.     (line 1419)
+* value-get keyword:                     Widget Gallery.     (line  851)
+* value-inline keyword:                  Widget Gallery.     (line  863)
+* value-set keyword:                     Widget Gallery.     (line  855)
+* value-to-external keyword:             Widget Gallery.     (line  829)
+* value-to-internal keyword:             Widget Gallery.     (line  821)
+* variable:                              atoms.              (line 2214)
+* variable-item:                         constants.          (line 2098)
+* variable-link widget:                  variable-link.      (line 1282)
+* vector:                                composite.          (line 2320)
+* void keyword:                          menu-choice.        (line 1519)
+* widget browser:                        Inspecting Widgets. (line 2462)
+* widget buttons:                        User Interface.     (line  202)
+* widget creation, widget conversion:    Setting Up the Buffer.
                                                              (line  399)
-* widget-button-suffix:                  Basic Types.        (line  449)
-* widget-children-validate:              Basic Types.        (line  567)
-* widget-choose:                         Utilities.          (line 1406)
+* widget inheritance:                    Widgets Basics.     (line  355)
+* widget library, why use it:            Introduction.       (line  116)
+* widget minor mode:                     Widget Minor Mode.  (line 2501)
+* widget object:                         Widgets Basics.     (line  349)
+* widget properties:                     Widgets Basics.     (line  391)
+* widget syntax:                         Widget Gallery.     (line  754)
+* widget value:                          Widgets Basics.     (line  374)
+* widget-apply:                          Working with Widgets.
+                                                             (line  564)
+* widget-apply-action:                   Working with Widgets.
+                                                             (line  636)
+* widget-at:                             Working with Widgets.
+                                                             (line  558)
+* widget-backward:                       Widgets and the Buffer.
+                                                             (line  706)
+* widget-browse:                         Inspecting Widgets. (line 2468)
+* widget-browse-at:                      Inspecting Widgets. (line 2478)
+* widget-browse-other-window:            Inspecting Widgets. (line 2473)
+* widget-button-click:                   Widgets and the Buffer.
+                                                             (line  741)
+* widget-button-click <1>:               Widgets and the Buffer.
+                                                             (line  741)
+* widget-button-face:                    Customization.      (line 2582)
+* widget-button-prefix:                  Customization.      (line 2610)
+* widget-button-press:                   Widgets and the Buffer.
+                                                             (line  731)
+* widget-button-press <1>:               Widgets and the Buffer.
+                                                             (line  731)
+* widget-button-suffix:                  Customization.      (line 2613)
+* widget-child-validate:                 Working with Widgets.
+                                                             (line  647)
+* widget-child-value-get:                Working with Widgets.
+                                                             (line  605)
+* widget-child-value-inline:             Working with Widgets.
+                                                             (line  608)
+* widget-children-validate:              Working with Widgets.
+                                                             (line  653)
+* widget-children-value-delete:          Setting Up the Buffer.
+                                                             (line  482)
+* widget-choice-toggle:                  Customization.      (line 2628)
+* widget-choose:                         Utilities.          (line 2533)
+* widget-complete:                       Widgets and the Buffer.
+                                                             (line  722)
+* widget-convert:                        Setting Up the Buffer.
+                                                             (line  504)
+* widget-copy:                           Setting Up the Buffer.
+                                                             (line  494)
 * widget-create:                         Setting Up the Buffer.
-                                                             (line  374)
-* widget-default-delete:                 Defining New Widgets.
-                                                             (line 1292)
-* widget-default-format-handler:         Defining New Widgets.
-                                                             (line 1329)
+                                                             (line  414)
+* widget-create-child:                   Setting Up the Buffer.
+                                                             (line  443)
+* widget-create-child-and-convert:       Setting Up the Buffer.
+                                                             (line  433)
+* widget-create-child-value:             Setting Up the Buffer.
+                                                             (line  449)
+* widget-default-delete:                 Widget Gallery.     (line  800)
+* widget-default-format-handler:         Widget Gallery.     (line 1046)
+* widget-default-get:                    Working with Widgets.
+                                                             (line  592)
 * widget-delete:                         Setting Up the Buffer.
-                                                             (line  381)
-* widget-field-face:                     User Interface.     (line  194)
-* widget-field-keymap:                   editable-field.     (line  691)
-* widget-forward:                        User Interface.     (line  263)
-* widget-get:                            Widget Properties.  (line 1162)
-* widget-get-sibling:                    Utilities.          (line 1402)
-* widget-global-map:                     Setting Up the Buffer.
-                                                             (line  404)
-* widget-image-directory:                Basic Types.        (line  595)
-* widget-image-enable:                   Basic Types.        (line  600)
+                                                             (line  479)
+* widget-describe:                       Inspecting Widgets. (line 2485)
+* widget-documentation-link-p:           Customization.      (line 2640)
+* widget-documentation-link-regexp:      Customization.      (line 2636)
+* widget-documentation-link-type:        Customization.      (line 2647)
+* widget-documentation-links:            Customization.      (line 2633)
+* widget-echo-help:                      Utilities.          (line 2567)
+* widget-end-of-line:                    Widgets and the Buffer.
+                                                             (line  713)
+* widget-field-activate:                 Widgets and the Buffer.
+                                                             (line  726)
+* widget-field-at:                       Working with Widgets.
+                                                             (line  561)
+* widget-field-face:                     Customization.      (line 2579)
+* widget-field-keymap:                   editable-field.     (line 1400)
+* widget-forward:                        Widgets and the Buffer.
+                                                             (line  702)
+* widget-get:                            Working with Widgets.
+                                                             (line  548)
+* widget-get-sibling:                    Utilities.          (line 2529)
+* widget-global-map:                     Widgets and the Buffer.
+                                                             (line  692)
+* widget-image-conversion:               Customization.      (line 2602)
+* widget-image-directory:                Customization.      (line 2591)
+* widget-image-enable:                   Customization.      (line 2598)
+* widget-image-find:                     Utilities.          (line 2553)
+* widget-image-insert:                   Utilities.          (line 2561)
 * widget-insert:                         Setting Up the Buffer.
-                                                             (line  393)
-* widget-keymap:                         Setting Up the Buffer.
-                                                             (line  399)
-* widget-link-prefix:                    link.               (line  616)
-* widget-link-suffix:                    link.               (line  619)
-* widget-member:                         Widget Properties.  (line 1167)
-* widget-minor-mode:                     Widget Minor Mode.  (line 1388)
-* widget-minor-mode-keymap:              Widget Minor Mode.  (line 1392)
-* widget-mouse-face:                     User Interface.     (line  252)
-* widget-parent-action:                  Defining New Widgets.
-                                                             (line 1339)
-* widget-prompt-value:                   Utilities.          (line 1398)
-* widget-push-button-prefix:             push-button.        (line  654)
-* widget-push-button-suffix:             push-button.        (line  657)
-* widget-put:                            Widget Properties.  (line 1158)
+                                                             (line  518)
+* widget-keymap:                         Widgets and the Buffer.
+                                                             (line  681)
+* widget-kill-line:                      Widgets and the Buffer.
+                                                             (line  718)
+* widget-link-prefix:                    Customization.      (line 2622)
+* widget-link-suffix:                    Customization.      (line 2625)
+* widget-member:                         Working with Widgets.
+                                                             (line  544)
+* widget-menu-max-shortcuts:             Customization.      (line 2659)
+* widget-menu-max-size:                  Customization.      (line 2653)
+* widget-menu-minibuffer-flag:           Customization.      (line 2665)
+* widget-minor-mode:                     Widget Minor Mode.  (line 2505)
+* widget-minor-mode-keymap:              Widget Minor Mode.  (line 2509)
+* widget-mouse-face:                     Customization.      (line 2585)
+* widget-parent-action:                  Working with Widgets.
+                                                             (line  642)
+* widget-prompt-value:                   Utilities.          (line 2518)
+* widget-push-button-prefix:             Customization.      (line 2616)
+* widget-push-button-suffix:             Customization.      (line 2619)
+* widget-put:                            Working with Widgets.
+                                                             (line  554)
 * widget-radio-add-item:                 radio-button-choice.
-                                                             (line  778)
+                                                             (line 1672)
 * widget-setup:                          Setting Up the Buffer.
-                                                             (line  384)
-* widget-text-keymap:                    text.               (line  701)
-* widget-type:                           Widget Properties.  (line 1178)
-* widget-types-convert-widget:           Defining New Widgets.
-                                                             (line 1252)
-* widget-types-copy:                     Defining New Widgets.
-                                                             (line 1266)
-* widget-value:                          Widget Properties.  (line 1139)
-* widget-value-convert-widget:           Defining New Widgets.
-                                                             (line 1255)
-* widget-value-set:                      Widget Properties.  (line 1143)
-* widget-value-value-get:                Defining New Widgets.
-                                                             (line 1320)
-* widgets, basic types:                  Introduction.       (line   63)
+                                                             (line  466)
+* widget-text-keymap:                    text.               (line 1491)
+* widget-type:                           Working with Widgets.
+                                                             (line  537)
+* widget-type-default-get:               Working with Widgets.
+                                                             (line  601)
+* widget-type-match:                     Working with Widgets.
+                                                             (line  658)
+* widget-type-value-create:              Working with Widgets.
+                                                             (line  615)
+* widget-types-convert-widget:           Working with Widgets.
+                                                             (line  670)
+* widget-types-copy:                     Working with Widgets.
+                                                             (line  664)
+* widget-value:                          Working with Widgets.
+                                                             (line  570)
+* widget-value-convert-widget:           Working with Widgets.
+                                                             (line  624)
+* widget-value-set:                      Working with Widgets.
+                                                             (line  583)
+* widget-value-value-get:                Working with Widgets.
+                                                             (line  629)
+* widgetp:                               Working with Widgets.
+                                                             (line  534)
+* widgets, basic types:                  Introduction.       (line   75)
 * widgets, programming example:          Programming Example.
-                                                             (line  273)
+                                                             (line  253)
 
