emacs-27 ed25282: Document effect of 'search-upper-case' on replacement commands

[Eli Zaretskii]

branch: emacs-27
commit ed25282b82732a7370a4a55633c5830fd473a9b7
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Document effect of 'search-upper-case' on replacement commands
    
    * doc/emacs/search.texi (Replacement and Lax Matches): Document
    the role of 'search-upper-case' in replacement commands.
    (Lax Search): Document the value 'not-yanks' of
    'search-upper-case' where the variable itself is documented.
    
    * lisp/replace.el (query-replace-regexp, query-replace): Mention
    'search-upper-case' and its effect in doc strings.  (Bug#40940)
---
 doc/emacs/search.texi | 22 +++++++++++++++-------
 lisp/replace.el       | 35 +++++++++++++++++++++--------------
 2 files changed, 36 insertions(+), 21 deletions(-)

diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index 1691661..2e094f3 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -1324,10 +1324,14 @@ case-sensitive.  Thus, searching for @samp{Foo} does 
not find
 @samp{foo} or @samp{FOO}.  This applies to regular expression search
 as well as to literal string search.  The effect ceases if you delete
 the upper-case letter from the search string.  The variable
-@code{search-upper-case} controls this: if it is non-@code{nil} (the
-default), an upper-case character in the search string makes the
-search case-sensitive; setting it to @code{nil} disables this effect
-of upper-case characters.
+@code{search-upper-case} controls this: if it is non-@code{nil}, an
+upper-case character in the search string makes the search
+case-sensitive; setting it to @code{nil} disables this effect of
+upper-case characters.  The default value of this variable is
+@code{not-yanks}, which makes search case-sensitive if there are
+upper-case letters in the search string, and also causes text yanked
+into the search string (@pxref{Isearch Yank}) to be down-cased, so
+that such searches are case-insensitive by default.
 
 @vindex case-fold-search
   If you set the variable @code{case-fold-search} to @code{nil}, then
@@ -1572,9 +1576,13 @@ searching for patterns.
 @cindex case folding in replace commands
   If the first argument of a replace command is all lower case, the
 command ignores case while searching for occurrences to
-replace---provided @code{case-fold-search} is non-@code{nil}.  If
-@code{case-fold-search} is set to @code{nil}, case is always significant
-in all searches.
+replace---provided @code{case-fold-search} is non-@code{nil} and
+@code{search-upper-case} is also non-@code{nil}.  If
+@code{search-upper-case} (@pxref{Lax Search, search-upper-case}) is
+@code{nil}, whether searching ignores case is determined by
+@code{case-fold-search} alone, regardless of letter-case of the
+command's first argument.  If @code{case-fold-search} is set to
+@code{nil}, case is always significant in all searches.
 
 @vindex case-replace
   In addition, when the @var{newstring} argument is all or partly lower
diff --git a/lisp/replace.el b/lisp/replace.el
index 491bf33..0880cbd 100644
--- a/lisp/replace.el
+++ b/lisp/replace.el
@@ -340,13 +340,17 @@ that reads FROM-STRING, or invoke replacements from
 incremental search with a key sequence like `C-s C-s M-%'
 to use its current search string as the string to replace.
 
-Matching is independent of case if `case-fold-search' is non-nil and
-FROM-STRING has no uppercase letters.  Replacement transfers the case
-pattern of the old text to the new text, if `case-replace' and
-`case-fold-search' are non-nil and FROM-STRING has no uppercase
-letters.  (Transferring the case pattern means that if the old text
-matched is all caps, or capitalized, then its replacement is upcased
-or capitalized.)
+Matching is independent of case if both `case-fold-search'
+and `search-upper-case' are non-nil and FROM-STRING has no
+uppercase letters; if `search-upper-case' is nil, then
+whether matching ignores case depends on `case-fold-search'
+regardless of whether there are uppercase letters in FROM-STRING.
+Replacement transfers the case pattern of the old text to the
+new text, if both `case-fold-search' and `case-replace' are
+non-nil and FROM-STRING has no uppercase letters.
+\(Transferring the case pattern means that if the old text
+matched is all caps, or capitalized, then its replacement is
+respectively upcased or capitalized.)
 
 Ignore read-only matches if `query-replace-skip-read-only' is non-nil,
 ignore hidden matches if `search-invisible' is nil, and ignore more
@@ -402,13 +406,16 @@ that reads REGEXP, or invoke replacements from
 incremental search with a key sequence like `C-M-s C-M-s C-M-%'
 to use its current search regexp as the regexp to replace.
 
-Matching is independent of case if `case-fold-search' is non-nil and
-REGEXP has no uppercase letters.  Replacement transfers the case
-pattern of the old text to the new text, if `case-replace' and
-`case-fold-search' are non-nil and REGEXP has no uppercase letters.
-\(Transferring the case pattern means that if the old text matched is
-all caps, or capitalized, then its replacement is upcased or
-capitalized.)
+Matching is independent of case if both `case-fold-search'
+and `search-upper-case' are non-nil and REGEXP has no uppercase
+letters; if `search-upper-case' is nil, then whether matching
+ignores case depends on `case-fold-search' regardless of whether
+there are uppercase letters in REGEXP.
+Replacement transfers the case pattern of the old text to the new
+text, if both `case-fold-search' and `case-replace' are non-nil
+and REGEXP has no uppercase letters.  (Transferring the case pattern
+means that if the old text matched is all caps, or capitalized,
+then its replacement is respectively upcased or capitalized.)
 
 Ignore read-only matches if `query-replace-skip-read-only' is non-nil,
 ignore hidden matches if `search-invisible' is nil, and ignore more