mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2025-02-04 20:27:45 +00:00
Code Issues Releases 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 49eb03d6c8a181fd46adbbcf1f0a976d0a9efa87)
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
Show Stats 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.
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

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
@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.
the language's syntax. Identifiers are also known as @dfn{tags}.
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
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

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 ()
"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)
@ -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,
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