emacs-27 5932df7: Document that the :match function for a widget takes an external value

[Mauro Aranda]

branch: emacs-27
commit 5932df74354316e117b2e6a43dc3ffd748aa7c7f
Author: Mauro Aranda <maurooaranda@gmail.com>
Commit: Mauro Aranda <maurooaranda@gmail.com>

    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)
---
 doc/misc/widget.texi | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/doc/misc/widget.texi b/doc/misc/widget.texi
index bccfa0a..2dde6ce 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