From 69521ffcb0f2a28f84e24137bfc789ffd0ec3f2f Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Wed, 4 May 2022 11:46:01 +0300 Subject: Clarify the doc string of 'with-buffer-unmodified-if-unchanged' * lisp/emacs-lisp/subr-x.el (with-buffer-unmodified-if-unchanged): Describe better what is meant by "buffer changes". (Bug#4587) --- lisp/emacs-lisp/subr-x.el | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) (limited to 'lisp/emacs-lisp') diff --git a/lisp/emacs-lisp/subr-x.el b/lisp/emacs-lisp/subr-x.el index 298d370cb25..9339acc9096 100644 --- a/lisp/emacs-lisp/subr-x.el +++ b/lisp/emacs-lisp/subr-x.el @@ -417,16 +417,23 @@ this defaults to the current buffer." process))) (defmacro with-buffer-unmodified-if-unchanged (&rest body) - "Like `progn', but change buffer modification status only if buffer is changed. -That is, if the buffer is marked as unmodified before BODY, and -BODY does modifications that, in total, means that the buffer is -identical to the buffer before BODY, mark the buffer as -unmodified again. In other words, this won't change buffer -modification status: + "Like `progn', but change buffer-modified status only if buffer text changes. +If the buffer was unmodified before execution of BODY, and +buffer text after execution of BODY is identical to what it was +before, ensure that buffer is still marked unmodified afterwards. +For example, the following won't change the buffer's modification +status: (with-buffer-unmodified-if-unchanged (insert \"a\") - (delete-char -1))." + (delete-char -1)) + +Note that only changes in the raw byte sequence of the buffer text, +as stored in the internal representation, are monitored for the +purpose of detecting the lack of changes in buffer text. Any other +changes that are normally perceived as \"buffer modifications\", such +as changes in text properties, `buffer-file-coding-system', buffer +multibytenes, etc. -- will still cause the buffer to become modified." (declare (debug t) (indent 0)) (let ((hash (gensym)) (buffer (gensym))) -- cgit v1.2.3