master 49eb03d: Improve documentation of 'read-regexp' and friends

[Eli Zaretskii]

branch: master
commit 49eb03d6c8a181fd46adbbcf1f0a976d0a9efa87
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Improve documentation of 'read-regexp' and friends
    
    * doc/emacs/glossary.texi (Glossary): Add "Tag" to the Glossary.
    * doc/emacs/maintaining.texi (Xref): Mention that identifiers are
    also known as "tags".
    
    * lisp/replace.el (read-regexp, read-regexp-suggestions): Improve
    wording of doc strings.  (Bug#46088)  (Bug#46089)
---
 doc/emacs/glossary.texi    |  8 ++++++--
 doc/emacs/maintaining.texi | 22 ++++++++++++----------
 lisp/replace.el            | 44 +++++++++++++++++++++++---------------------
 3 files changed, 41 insertions(+), 33 deletions(-)

diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi
index 35df065..4f971eb 100644
--- a/doc/emacs/glossary.texi
+++ b/doc/emacs/glossary.texi
@@ -1369,10 +1369,14 @@ configurations.  @xref{Tab Bars}.
 The tab line is a line of tabs at the top of an Emacs window.
 Clicking on one of these tabs switches window buffers.  @xref{Tab Line}.
 
+@item Tag
+A tag is an identifier in a program source.  @xref{Xref}.
+
 @anchor{Glossary---Tags Table}
 @item Tags Table
-A tags table is a file that serves as an index to the function
-definitions in one or more other files.  @xref{Tags Tables}.
+A tags table is a file that serves as an index to identifiers: definitions
+of functions, macros, data structures, etc., in one or more other files.
+@xref{Tags Tables}.
 
 @item Termscript File
 A termscript file contains a record of all characters sent by Emacs to
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 4158154..bc276c4 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1994,19 +1994,21 @@ Of course, you should substitute the proper years and 
copyright holder.
 @section Find Identifier References
 @cindex xref
 
+@cindex tag
   An @dfn{identifier} is a name of a syntactical subunit of the
 program: a function, a subroutine, a method, a class, a data type, a
 macro, etc.  In a programming language, each identifier is a symbol in
-the language's syntax.  Program development and maintenance requires
-capabilities to quickly find where each identifier was defined and
-referenced, to rename identifiers across the entire project, etc.
-
-These capabilities are also useful for finding references in major
-modes other than those defined to support programming languages.  For
-example, chapters, sections, appendices, etc.@: of a text or a @TeX{}
-document can be treated as subunits as well, and their names can be
-used as identifiers.  In this chapter, we use the term ``identifiers''
-to collectively refer to the names of any kind of subunits, in program
+the language's syntax.  Identifiers are also known as @dfn{tags}.
+
+Program development and maintenance requires capabilities to quickly
+find where each identifier was defined and referenced, to rename
+identifiers across the entire project, etc.  These capabilities are
+also useful for finding references in major modes other than those
+defined to support programming languages.  For example, chapters,
+sections, appendices, etc.@: of a text or a @TeX{} document can be
+treated as subunits as well, and their names can be used as
+identifiers.  In this chapter, we use the term ``identifiers'' to
+collectively refer to the names of any kind of subunits, in program
 source and in other kinds of text alike.
 
 Emacs provides a unified interface to these capabilities, called
diff --git a/lisp/replace.el b/lisp/replace.el
index 32fbc24..4483d7f 100644
--- a/lisp/replace.el
+++ b/lisp/replace.el
@@ -808,11 +808,11 @@ the function that you set this to can check 
`this-command'."
 
 (defun read-regexp-suggestions ()
   "Return a list of standard suggestions for `read-regexp'.
-By default, the list includes the \"tag\" at point (see Info
-node `(emacs) Identifier Search'), the last isearch regexp, the
-last isearch string, and the last replacement regexp.
-`read-regexp' appends the list returned by this function to the
-end of values available via
+By default, the list includes the identifier (a.k.a. \"tag\")
+at point (see Info node `(emacs) Identifier Search'), the last
+isearch regexp, the last isearch string, and the last
+replacement regexp.  `read-regexp' appends the list returned
+by this function to the end of values available via
 \\<minibuffer-local-map>\\[next-history-element]."
   (list
    (find-tag-default-as-regexp)
@@ -827,33 +827,35 @@ Prompt with the string PROMPT.  If PROMPT ends in \":\" 
(followed by
 optional whitespace), use it as-is.  Otherwise, add \": \" to the end,
 possibly preceded by the default result (see below).
 
-The optional argument DEFAULTS can be either: nil, a string, a list
-of strings, or a symbol.  We use DEFAULTS to construct the default
-return value in case of empty input.
+The optional argument DEFAULTS is used to construct the default
+return value in case of empty input.  DEFAULTS can be nil, a string,
+a list of strings, or a symbol.
 
-If DEFAULTS is a string, we use it as-is.
+If DEFAULTS is a string, the function uses it as-is.
 
 If DEFAULTS is a list of strings, the first element is the
 default return value, but all the elements are accessible
 using the history command \\<minibuffer-local-map>\\[next-history-element].
 
-DEFAULTS can be a symbol.  If DEFAULTS is the symbol
-`regexp-history-last', we use the first element of HISTORY (if
-specified) or `regexp-history'.  If DEFAULTS is a symbol with a
-function definition, we call it with no arguments and use what it
-returns, which should be either nil, a string, or a list of
-strings.  Other symbol values for DEFAULTS are ignored.  If
-`read-regexp-defaults-function' is non-nil, its value is used
-instead of DEFAULTS in the two cases described in this paragraph.
+If DEFAULTS is the symbol `regexp-history-last', the default return
+value will be the first element of HISTORY.  If HISTORY is omitted or
+nil, `regexp-history' is used instead.
+If DEFAULTS is a symbol with a function definition, it is called with
+no arguments and should return either nil, a string, or a list of
+strings, which will be used as above.
+Other symbol values for DEFAULTS are ignored.
 
-We append the standard values from `read-regexp-suggestions' to DEFAULTS
-before using it.
+If `read-regexp-defaults-function' is non-nil, its value is used
+instead of DEFAULTS in the two cases described in the last paragraph.
+
+Before using whatever value DEFAULTS yields, the function appends the
+standard values from `read-regexp-suggestions' to that value.
 
 If the first element of DEFAULTS is non-nil (and if PROMPT does not end
-in \":\", followed by optional whitespace), we add it to the prompt.
+in \":\", followed by optional whitespace), DEFAULT is added to the prompt.
 
 The optional argument HISTORY is a symbol to use for the history list.
-If nil, uses `regexp-history'."
+If nil, use `regexp-history'."
   (let* ((defaults
           (if (and defaults (symbolp defaults))
               (cond