1 files changed, 34 insertions, 19 deletions

diff --git a/lispref/searching.texi b/lispref/searching.texi
index 1f4a82d3f1f..15037068dd2 100644
--- a/lispref/searching.texi
+++ b/lispref/searching.texi
@@ -1485,13 +1485,14 @@ character of the buffer counts as 1.)
   The functions @code{match-data} and @code{set-match-data} read or
 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
+@defun match-data &optional integers reuse reseat
+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,16 @@ 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.
+
+If @var{reseat} is non-@code{nil}, all markers on the @var{reuse} list
+are reseated to point to nowhere, and if the value is @code{evaporate},
+the markers are put back on the free list.
+
+@strong{Warning:} When @code{evaporate} is specified for @var{reseat},
+no other references to the markers on the @var{reuse} list; otherwise,
+Emacs may crash during the next 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
@@ -1542,7 +1549,7 @@ intended to access the match data for that search.
 @end example
 @end defun
 
-@defun set-match-data match-list
+@defun set-match-data match-list &optional reseat
 This function sets the match data from the elements of @var{match-list},
 which should be a list that was the value of a previous call to
 @code{match-data}.  (More precisely, anything that has the same format
@@ -1551,6 +1558,14 @@ will work.)
 If @var{match-list} refers to a buffer that doesn't exist, you don't get
 an error; that sets the match data in a meaningless but harmless way.
 
+If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list
+are reseated to point to nowhere, and if the value is @code{evaporate},
+the markers are put back on the free list.
+
+@strong{Warning:} When @code{evaporate} is specified for @var{reseat},
+no other references to the markers on the @var{match-list} list; otherwise,
+Emacs may crash during the next garbage collection.
+
 @findex store-match-data
 @code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
 @end defun