(Entire Match Data): Clarify when match-data

returns markers and when integers.

1 files changed, 16 insertions, 17 deletions

diff --git a/lispref/searching.texi b/lispref/searching.texi
index 1f4a82d3f1f..01d055c4a45 100644
--- a/lispref/searching.texi
+++ b/lispref/searching.texi
@@ -1486,12 +1486,13 @@ character of the buffer counts as 1.)
 write the entire match data, all at once.
 
 @defun match-data &optional integers reuse
-This function returns a newly constructed list containing all the
-information on what text the last search matched.  Element zero is the
-position of the beginning of the match for the whole expression; element
-one is the position of the end of the match for the expression.  The
-next two elements are the positions of the beginning and end of the
-match for the first subexpression, and so on.  In general, element
+This function returns a list of positions (markers or integers) that
+record all the information on what text the last search matched.
+Element zero is the position of the beginning of the match for the
+whole expression; element one is the position of the end of the match
+for the expression.  The next two elements are the positions of the
+beginning and end of the match for the first subexpression, and so on.
+In general, element
 @ifnottex
 number 2@var{n}
 @end ifnottex
@@ -1508,15 +1509,13 @@ number {\mathsurround=0pt $2n+1$}
 @end tex
 corresponds to @code{(match-end @var{n})}.
 
-All the elements are markers or @code{nil} if matching was done on a
-buffer and all are integers or @code{nil} if matching was done on a
-string with @code{string-match}.   If @var{integers} is
-non-@code{nil}, then the elements are integers or @code{nil}, even if
-matching was done on a buffer.  In that case, the buffer itself is
-appended as an additional element at the end of the list
-to facilitate complete restoration of the match data.  Also,
-@code{match-beginning} and
-@code{match-end} always return integers or @code{nil}.
+Normally all the elements are markers or @code{nil}, but if
+@var{integers} is non-@code{nil}, that means to use integers instead
+of markers.  (In that case, the buffer itself is appended as an
+additional element at the end of the list, to facilitate complete
+restoration of the match data.)  If the last match was done on a
+string with @code{string-match}, then integers are always used,
+since markers can't point into a string.
 
 If @var{reuse} is non-@code{nil}, it should be a list.  In that case,
 @code{match-data} stores the match data in @var{reuse}.  That is,
@@ -1524,8 +1523,8 @@ If @var{reuse} is non-@code{nil}, it should be a list.  In that case,
 have the right length.  If it is not long enough to contain the match
 data, it is extended.  If it is too long, the length of @var{reuse}
 stays the same, but the elements that were not used are set to
-@code{nil}.  The purpose of this feature is to avoid producing too
-much garbage, that would later have to be collected.
+@code{nil}.  The purpose of this feature is to reduce the need for
+garbage collection.
 
 As always, there must be no possibility of intervening searches between
 the call to a search function and the call to @code{match-data} that is