[Emacs-diffs] master 84f992d 7/7: Merge from origin/emacs-26

[Glenn Morris]

branch: master
commit 84f992d42e3a4c21db9994b8c6585c336cb05163
Merge: d3f94d2 4cfe531
Author: Glenn Morris <address@hidden>
Commit: Glenn Morris <address@hidden>

    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'
---
 doc/lispref/buffers.texi | 22 ++++++++++++++++++----
 doc/lispref/syntax.texi  | 12 +++++++-----
 doc/lispref/text.texi    |  7 ++++---
 lisp/newcomment.el       |  5 +++--
 src/xdisp.c              |  7 ++++++-
 5 files changed, 38 insertions(+), 15 deletions(-)

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index cfd2fb7..1acf4ba 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
address@hidden macro.
+
address@hidden with-silent-modifications address@hidden
+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.
address@hidden 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 address@hidden, that means to display the new
-buffer by calling @code{pop-to-buffer}.  If @var{norecord} is
address@hidden, that means not to put the new buffer to the front of
-the buffer list.
+If @var{display-flag} is address@hidden, as it always is in
+interactive calls, that means to display the new buffer by calling
address@hidden  If @var{norecord} is address@hidden, 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 44a7730..71c97fd 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
address@hidden, 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''.
address@hidden, 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 da09b4a..2afcd59 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
address@hidden 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 0e983fd..cd72266 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 1299ba3..ad1c044 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 ();