From 49eb03d6c8a181fd46adbbcf1f0a976d0a9efa87 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Wed, 27 Jan 2021 17:15:46 +0200 Subject: [PATCH] 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 35df06591eb..4f971eb1e01 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 415815473e5..bc276c49046 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 32fbc24064c..4483d7f7800 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 \\\\[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 \\\\[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 -- 2.39.2