1 files changed, 49 insertions, 8 deletions

diff --git a/doc/misc/widget.texi b/doc/misc/widget.texi
index 3c8b4c8819a..c84b49a038c 100644
--- a/doc/misc/widget.texi
+++ b/doc/misc/widget.texi
@@ -9,7 +9,7 @@
 @c %**end of header
 
 @copying
-Copyright @copyright{} 2000--2017 Free Software Foundation, Inc.
+Copyright @copyright{} 2000--2022 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -484,9 +484,21 @@ are interpreted in a widget specific way.
 The following keyword arguments apply to all widgets:
 
 @table @code
+@cindex internal format
+@cindex external format
 @vindex value@r{ keyword}
 @item :value
-The initial value for widgets of this type.
+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
+stored in the @code{:value} property has.  However, when creating a
+widget or defining a new one (@pxref{Defining New Widgets}), the
+@code{:value} should be in the external format.
 
 @vindex format@r{ keyword}
 @item :format
@@ -629,8 +641,9 @@ representation of the @code{:value} property if not.
 
 @vindex match@r{ keyword}
 @item :match
-Should be a function called with two arguments, the widget and a value,
-and returning non-@code{nil} if the widget can represent the specified value.
+Should be a function called with two arguments, the widget and an
+external value, and should return non-@code{nil} if the widget can
+represent the specified value.
 
 @vindex validate@r{ keyword}
 @item :validate
@@ -679,14 +692,14 @@ arguments, which will be used when creating the @code{radio-button} or
 
 @end table
 
-@deffn {User Option} widget-glyph-directory
-Directory where glyphs are found.
+@deffn {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 @file{.xpm} (if supported) or @file{.xbm} extension.
 @end deffn
 
-@deffn{User Option} widget-glyph-enable
-If non-@code{nil}, allow glyphs to appear on displays where they are supported.
+@deffn{User Option} widget-image-enable
+If non-@code{nil}, allow images to appear on displays where they are supported.
 @end deffn
 
 
@@ -1446,6 +1459,12 @@ Non-@code{nil} if @var{widget} has a value (even @code{nil}) for
 property @var{property}.
 @end defun
 
+@defun widget-apply widget property &rest args
+Apply the value of @var{property} to @var{widget}, passing @var{args}
+as additional arguments to the function.  Return the result of that
+function call.
+@end defun
+
 Occasionally it can be useful to know which kind of widget you have,
 i.e., the name of the widget type you gave when the widget was created.
 
@@ -1734,6 +1753,28 @@ Get the item which @var{widget} is assumed to toggle.
 This is only meaningful for radio buttons or checkboxes in a list.
 @end defun
 
+@defun widget-choose title items &optional event
+Prompt the user to choose an item from a list of options.
+
+@var{title} is the name of the list of options.  @var{items} should be
+a menu, with its items in the simple format or in the extended format.
+@xref{Defining Menus,, Defining Menus, elisp, the Emacs Lisp Reference
+Manual}.  Independently of the format, you don't have to provide a
+title for the menu, just pass the desired title in @var{title}.  The
+optional @var{event} is an input event.  If @var{event} is a mouse
+event and the number of elements in @var{items} is less than the user
+option @code{widget-menu-max-size}, then @code{widget-choose} uses a
+popup menu to prompt the user.  Otherwise, @code{widget-choose} uses
+the minibuffer.
+
+When @var{items} is a keymap menu, the returned value is the symbol in
+the key vector, as in the argument of @code{define-key}
+(@pxref{Changing Key Bindings,,,elisp, the Emacs Lisp Reference
+Manual}).  When @var{items} is a list whose selectable items are of
+the form (@var{name} . @var{value}) (i.e., the simplified format),
+then the return value is the @var{value} of the chosen element.
+@end defun
+
 @node  Widget Wishlist
 @chapter Wishlist
 @cindex todo