From 641c94ce68399e89a35769cb8727c59412767faa Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 2 Jun 2018 13:27:22 +0300
Subject: [PATCH] Imp[rove documentation of 'with-silent-modifications'

* doc/lispref/buffers.texi (Buffer Modification): Document
'with-silent-modifications'.  (Bug#31613)
* doc/lispref/text.texi (Changing Properties): Add a
cross-reference to "Buffer Modification".  Improve wording.
---
 doc/lispref/buffers.texi | 14 ++++++++++++++
 doc/lispref/text.texi    |  7 ++++---
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 45e90669b7e..686b6162a55 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -587,6 +587,20 @@ in between the calls.  If @var{buffer} is @code{nil} (or omitted), the
 current buffer is used.
 @end defun
 
+Sometimes there's a need for modifying buffer in a way that doesn't
+really change its text, like if only its text properties are changed.
+If your program needs to modify a buffer without triggering any hooks
+and features that react to buffer modifications, use the
+@code{with-silent-modifications} macro.
+
+@defmac with-silent-modifications body@dots{}
+Execute @var{body} pretending it does not modify the buffer.  This
+includes checking whether the buffer's file is locked (@pxref{File
+Locks}), running buffer modification hooks (@pxref{Change Hooks}),
+etc.  Note that if @var{body} actually modifies the buffer text, its
+undo data may become corrupted.
+@end defmac
+
 @node Modification Time
 @section Buffer Modification Time
 @cindex comparing file modification time
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 6dde4c00f85..477b8fce719 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3037,9 +3037,10 @@ construct each part with @code{propertize} and then combine them with
 buffer but does not copy its properties.
 
 @findex with-silent-modifications
-  If you wish to add or remove text properties to a buffer without
-marking the buffer as modified, you can wrap the calls above in the
-@code{with-silent-modifications} macro.
+  If you wish to add text properties to a buffer or remove them
+without marking the buffer as modified, you can wrap the calls above
+in the @code{with-silent-modifications} macro.  @xref{Buffer
+Modification}.
 
 @node Property Search
 @subsection Text Property Search Functions
-- 
2.39.5