Merge from origin/emacs-26

4cfe531 (origin/emacs-26) Improve ELisp documentation of 'clone-indir...
9089b02 Improve documentation of 'inhibit-message'
6107e12 Improve documentation of comment styles
fb45125 Documentation improvements in newcomment.el
641c94c Imp[rove documentation of 'with-silent-modifications'

5 files changed, 38 insertions, 15 deletions

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index cfd2fb7715b..1acf4baedba 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
@@ -1167,10 +1181,10 @@ the current buffer's base buffer and copies the rest of the current
 buffer's attributes.  (If the current buffer is not indirect, it is
 used as the base buffer.)
 
-If @var{display-flag} is non-@code{nil}, that means to display the new
-buffer by calling @code{pop-to-buffer}.  If @var{norecord} is
-non-@code{nil}, that means not to put the new buffer to the front of
-the buffer list.
+If @var{display-flag} is non-@code{nil}, as it always is in
+interactive calls, that means to display the new buffer by calling
+@code{pop-to-buffer}.  If @var{norecord} is non-@code{nil}, that means
+not to put the new buffer to the front of the buffer list.
 @end deffn
 
 @defun buffer-base-buffer &optional buffer
diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index 44a7730c7ab..71c97fdae8c 100644
--- a/doc/lispref/syntax.texi
+++ b/doc/lispref/syntax.texi
@@ -339,11 +339,13 @@ same style will be recognized.  For a two-character comment delimiter,
 @cindex comment style
 Emacs supports several comment styles simultaneously in any one syntax
 table.  A comment style is a set of flags @samp{b}, @samp{c}, and
-@samp{n}, so there can be up to 8 different comment styles.
-Each comment delimiter has a style and only matches comment delimiters
-of the same style.  Thus if a comment starts with the comment-start
-sequence of style ``bn'', it will extend until the next matching
-comment-end sequence of style ``bn''.
+@samp{n}, so there can be up to 8 different comment styles, each one
+named by the set of its flags.  Each comment delimiter has a style and
+only matches comment delimiters of the same style.  Thus if a comment
+starts with the comment-start sequence of style ``bn'', it will extend
+until the next matching comment-end sequence of style ``bn''.  When
+the set of flags has neither flag @samp{b} nor flag @samp{c} set, the
+resulting style is called the ``a'' style.
 
 The appropriate comment syntax settings for C++ can be as follows:
 
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index da09b4ae1c6..2afcd59a706 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3038,9 +3038,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
diff --git a/lisp/newcomment.el b/lisp/newcomment.el
index 0e983fd9164..cd722663dad 100644
--- a/lisp/newcomment.el
+++ b/lisp/newcomment.el
@@ -895,7 +895,7 @@ If N is `re', a regexp is returned instead, that would match
 (defun uncomment-region (beg end &optional arg)
   "Uncomment each line in the BEG .. END region.
 The numeric prefix ARG can specify a number of chars to remove from the
-comment markers."
+comment delimiters."
   (interactive "*r\nP")
   (comment-normalize-vars)
   (when (> beg end) (setq beg (prog1 end (setq end beg))))
@@ -909,7 +909,8 @@ comment markers."
 (defun uncomment-region-default-1 (beg end &optional arg)
   "Uncomment each line in the BEG .. END region.
 The numeric prefix ARG can specify a number of chars to remove from the
-comment markers."
+comment delimiters.
+This function is the default value of `uncomment-region-function'."
   (goto-char beg)
   (setq end (copy-marker end))
   (let* ((numarg (prefix-numeric-value arg))
diff --git a/src/xdisp.c b/src/xdisp.c
index 1299ba38e3d..ad1c044557d 100644
--- a/src/xdisp.c
+++ b/src/xdisp.c
@@ -32449,7 +32449,12 @@ syms_of_xdisp (void)
 
   DEFVAR_BOOL("inhibit-message", inhibit_message,
               doc:  /* Non-nil means calls to `message' are not displayed.
-They are still logged to the *Messages* buffer.  */);
+They are still logged to the *Messages* buffer.
+
+Do NOT set this globally to a non-nil value, as doing that will
+disable messages everywhere, including in I-search and other
+places where they are necessary.  This variable is intended to
+be let-bound around code that needs to disable messages temporarily. */);
   inhibit_message = 0;
 
   message_dolog_marker1 = Fmake_marker ();