mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-01-21 03:52:16 -08:00
Code Issues Projects Releases Wiki Activity

Improve documentation of 'read-regexp' and friends

Browse source 
* 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)

(cherry picked from commit 49eb03d6c8)
This commit is contained in:
Eli Zaretskii 2021-01-27 17:15:46 +02:00
parent 0340e9eccb
commit e79e377a4e
3 changed files with 40 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

8
doc/emacs/glossary.texi
View file

@ -1369,10 +1369,14 @@ configurations. @xref{Tab Bars}.
The tab line is a line of tabs at the top of an Emacs window. 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}. 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} @anchor{Glossary---Tags Table}
@item Tags Table @item Tags Table
A tags table is a file that serves as an index to the function A tags table is a file that serves as an index to identifiers: definitions
definitions in one or more other files. @xref{Tags Tables}. of functions, macros, data structures, etc., in one or more other files.
@xref{Tags Tables}.
@item Termscript File @item Termscript File
A termscript file contains a record of all characters sent by Emacs to A termscript file contains a record of all characters sent by Emacs to

20
doc/emacs/maintaining.texi
View file

@ -1860,19 +1860,21 @@ Of course, you should substitute the proper years and copyright holder.
@section Find Identifier References @section Find Identifier References
@cindex xref @cindex xref
@cindex tag
An @dfn{identifier} is a name of a syntactical subunit of the 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 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 macro, etc. In a programming language, each identifier is a symbol in
the language's syntax. Program development and maintenance requires the language's syntax. Identifiers are also known as @dfn{tags}.
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 Program development and maintenance requires capabilities to quickly
modes other than those defined to support programming languages. For find where each identifier was defined and referenced, to rename
example, chapters, sections, appendices, etc.@: of a text or a @TeX{} identifiers across the entire project, etc. These capabilities are
document can be treated as subunits as well, and their names can be also useful for finding references in major modes other than those
used as identifiers. In this chapter, we use the term ``identifiers'' defined to support programming languages. For example, chapters,
to collectively refer to the names of any kind of subunits, in program 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. source and in other kinds of text alike.
Emacs provides a unified interface to these capabilities, called Emacs provides a unified interface to these capabilities, called

44
lisp/replace.el
View file

@ -786,11 +786,11 @@ the function that you set this to can check `this-command'."
(defun read-regexp-suggestions () (defun read-regexp-suggestions ()
"Return a list of standard suggestions for `read-regexp'. "Return a list of standard suggestions for `read-regexp'.
By default, the list includes the \"tag\" at point (see Info By default, the list includes the identifier (a.k.a. \"tag\")
node `(emacs) Identifier Search'), the last isearch regexp, the at point (see Info node `(emacs) Identifier Search'), the last
last isearch string, and the last replacement regexp. isearch regexp, the last isearch string, and the last
`read-regexp' appends the list returned by this function to the replacement regexp. `read-regexp' appends the list returned
end of values available via by this function to the end of values available via
\\<minibuffer-local-map>\\[next-history-element]." \\<minibuffer-local-map>\\[next-history-element]."
(list (list
(find-tag-default-as-regexp) (find-tag-default-as-regexp)
@ -805,33 +805,35 @@ Prompt with the string PROMPT. If PROMPT ends in \":\" (followed by
optional whitespace), use it as-is. Otherwise, add \": \" to the end, optional whitespace), use it as-is. Otherwise, add \": \" to the end,
possibly preceded by the default result (see below). possibly preceded by the default result (see below).
The optional argument DEFAULTS can be either: nil, a string, a list The optional argument DEFAULTS is used to construct the default
of strings, or a symbol. We use DEFAULTS to construct the default return value in case of empty input. DEFAULTS can be nil, a string,
return value in case of empty input. 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 If DEFAULTS is a list of strings, the first element is the
default return value, but all the elements are accessible default return value, but all the elements are accessible
using the history command \\<minibuffer-local-map>\\[next-history-element]. using the history command \\<minibuffer-local-map>\\[next-history-element].
DEFAULTS can be a symbol. If DEFAULTS is the symbol If DEFAULTS is the symbol `regexp-history-last', the default return
`regexp-history-last', we use the first element of HISTORY (if value will be the first element of HISTORY. If HISTORY is omitted or
specified) or `regexp-history'. If DEFAULTS is a symbol with a nil, `regexp-history' is used instead.
function definition, we call it with no arguments and use what it If DEFAULTS is a symbol with a function definition, it is called with
returns, which should be either nil, a string, or a list of no arguments and should return either nil, a string, or a list of
strings. Other symbol values for DEFAULTS are ignored. If strings, which will be used as above.
`read-regexp-defaults-function' is non-nil, its value is used Other symbol values for DEFAULTS are ignored.
instead of DEFAULTS in the two cases described in this paragraph.
We append the standard values from `read-regexp-suggestions' to DEFAULTS If `read-regexp-defaults-function' is non-nil, its value is used
before using it. 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 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. 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 (let* ((defaults
(if (and defaults (symbolp defaults)) (if (and defaults (symbolp defaults))
(cond (cond