Document that the :match function for a widget takes an external value

* doc/misc/widget.texi (Basic Types): Document what an external value
is.  Document that a :match function expects the value to be in the
external format.  (Bug#8717)

1 files changed, 16 insertions, 3 deletions

diff --git a/doc/misc/widget.texi b/doc/misc/widget.texi
index bccfa0ab6c1..2dde6ce4d3c 100644
--- a/doc/misc/widget.texi
+++ b/doc/misc/widget.texi
@@ -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