Merge from origin/emacs-27

d6a0b66a0c (origin/emacs-27) * lisp/subr.el (save-match-data): Clarif...
1a6d59eeba Improve the documentation of setting up fontsets
c7737d40f2 ; * etc/TODO (Ligatures): Update the entry based on recent...
fb2e34cd21 ; * etc/TODO (Ligatures): Update the entry based on recent...
13b6dfd4f7 * doc/emacs/killing.texi (Rectangles): Improve indexing.
a10254dd46 Fix accessing files on networked drives on MS-Windows

1 files changed, 5 insertions, 1 deletions

diff --git a/lisp/subr.el b/lisp/subr.el
index 324c59f13f7..10c37e94134 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -4112,7 +4112,11 @@ MODES is as for `set-default-file-modes'."
 ;; now, but it generates slower code.
 (defmacro save-match-data (&rest body)
   "Execute the BODY forms, restoring the global value of the match data.
-The value returned is the value of the last form in BODY."
+The value returned is the value of the last form in BODY.
+NOTE: The convention in Elisp is that any function, except for a few
+exceptions like car/assoc/+/goto-char, can clobber the match data,
+so `save-match-data' should normally be used to save *your* match data
+rather than your caller's match data."
   ;; It is better not to use backquote here,
   ;; because that makes a bootstrapping problem
   ;; if you need to recompile all the Lisp files using interpreted code.