From: Eli Zaretskii Date: Wed, 27 Jan 2021 15:15:46 +0000 (+0200) Subject: Improve documentation of 'read-regexp' and friends X-Git-Tag: emacs-27.1.91~2 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=e79e377a4e06d187e56dcad826fb761659abe3f3;p=emacs.git 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) (cherry picked from commit 49eb03d6c8a181fd46adbbcf1f0a976d0a9efa87) --- 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 14911d30e99..9bb3378c3f3 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -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. - -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 d1618a485ed..416d9f1d1ec 100644 --- a/lisp/replace.el +++ b/lisp/replace.el @@ -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 \\\\[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 \\\\[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