master b4158a7 1/2: Document 'tags-apropos-additional-actions' with Xref

[Eli Zaretskii]

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

    Document 'tags-apropos-additional-actions' with Xref
    
    * doc/emacs/maintaining.texi (Looking Up Identifiers): Rearrange
    and reword documentation of 'xref-find-apropos' and
    'xref-auto-jump-to-first-definition'.  Add the description of
    'tags-apropos-additional-actions'.  Delete the comment with
    not-yet implemented features that were available with
    'tags-apropos'.
    
    * etc/NEWS: Augment the wording of 'xref-find-apropos' entry.
---
 doc/emacs/maintaining.texi | 89 ++++++++++++++++++----------------------------
 etc/NEWS                   |  4 ++-
 2 files changed, 38 insertions(+), 55 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 64221f1..5a436a3 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -2141,31 +2141,15 @@ Switch @code{xref} to use the @code{etags} backend.
 @kindex M-.
 @findex xref-find-definitions
 @vindex xref-prompt-for-identifier
-  @kbd{M-.}@: (@code{xref-find-definitions}) shows the definitions of
+  @kbd{M-.}@: (@code{xref-find-definitions}) shows the definition of
 the identifier at point.  With a prefix argument, or if there's no
 identifier at point, it prompts for the identifier.  (If you want it
 to always prompt, customize @code{xref-prompt-for-identifier} to
 @code{t}.)
 
-@vindex xref-auto-jump-to-first-definition
-If the specified identifier has only one definition, the command jumps
-to it.  If the identifier has more than one possible definition (e.g.,
-in an object-oriented language, or if there's a function and a
-variable by the same name), the command shows the candidate
-definitions in the @file{*xref*} buffer, together with the files in
-which these definitions are found.  Selecting one of these candidates
-by typing @kbd{@key{RET}} or clicking @kbd{mouse-2} will pop a buffer
-showing the corresponding definition.  If the value of the variable
-@code{xref-auto-jump-to-first-definition} is @code{move}, the first
-of these candidates is automatically selected, and if it's @code{t} or
-@code{show}, the first candidate is automatically shown; @code{t} also
-selects the window showing the first candidate.  The default value is
-@code{nil}, which just shows the candidates in the @file{*xref*}
-buffer, but doesn't select any of them.
-
-  When entering the identifier argument to @kbd{M-.}, the usual
-minibuffer completion commands can be used (@pxref{Completion}), with
-the known identifier names as completion candidates.
+  When entering the identifier argument to @kbd{M-.}, you can use the
+usual minibuffer completion commands (@pxref{Completion}), with the
+known identifier names being the completion candidates.
 
 @kindex C-x 4 .
 @findex xref-find-definitions-other-window
@@ -2183,23 +2167,40 @@ former is @w{@kbd{C-x 4 .}}
 or around the place of a mouse event.  This command is intended to be
 bound to a mouse event, such as @kbd{C-M-mouse-1}, for example.
 
-@findex xref-find-apropos
 @kindex C-M-.
-  The command @kbd{C-M-.} (@code{xref-find-apropos}) finds the
-definitions of one or more identifiers that match a specified regular
-expression.  It is just like @kbd{M-.} except that it does regexp
+@findex xref-find-apropos
+@vindex tags-apropos-additional-actions
+  The command @kbd{C-M-.}@: (@code{xref-find-apropos}) is like
+@code{apropos} for tags (@pxref{Apropos}).  It displays a list of
+identifiers in the selected tags table whose names match the specified
+@var{regexp}.  This is just like @kbd{M-.}, except that it does regexp
 matching of identifiers instead of matching symbol names as fixed
-strings.
+strings.  By default, the command pops up the @file{*xref*} buffer,
+like @kbd{M-.}, but you can display additional output by customizing
+the variable @code{tags-apropos-additional-actions}; see its
+documentation for details.
 
-  When any of the above commands finds more than one definition, it
-presents the @file{*xref*} buffer showing the definition candidates.
-In that buffer, you have several specialized commands, described in
-@ref{Xref Commands}.
+@vindex xref-auto-jump-to-first-definition
+  If any of the above commands finds more than one matching
+definition, it by default pops up the @file{*xref*} buffer showing the
+matching candidates.  (@kbd{C-M-.}@: @emph{always} pops up the
+@file{*xref*} buffer if it finds at least one match.)  The candidates
+are normally shown in that buffer as the name of a file and the
+matching identifier(s) in that file.  In that buffer, you can select
+any of the candidates for display, and you have several additional
+commands, described in @ref{Xref Commands}.  However, if the value of
+the variable @code{xref-auto-jump-to-first-definition} is @code{move},
+the first of these candidates is automatically selected in the
+@file{*xref*} buffer, and if it's @code{t} or @code{show}, the first
+candidate is automatically shown in its own window; @code{t} also
+selects the window showing the first candidate.  The default value is
+@code{nil}, which just shows the candidates in the @file{*xref*}
+buffer, but doesn't select any of them.
 
 @kindex M-,
 @findex xref-pop-marker-stack
 @vindex xref-marker-ring-length
-  To go back to places @emph{from where} you found the definition,
+  To go back to places @emph{from where} you've displayed the definition,
 use @kbd{M-,} (@code{xref-pop-marker-stack}).  It jumps back to the
 point of the last invocation of @kbd{M-.}.  Thus you can find and
 examine the definition of something with @kbd{M-.} and then return to
@@ -2410,15 +2411,14 @@ Searching}.
 Perform completion on the text around point, possibly using the
 selected tags table if one is loaded (@code{completion-at-point}).
 
-@item M-x xref-find-apropos @key{RET} @var{regexp} @key{RET}
-Display a list of all known identifiers matching @var{regexp}.
-The way this command displays the matches is affected by the value of
-@code{xref-auto-jump-to-first-xref} (@pxref{Identifier Search}).
-
 @item M-x list-tags @key{RET} @var{file} @key{RET}
 Display a list of the identifiers defined in the program file
 @var{file}.
 
+@item C-M-. @var{regexp} @key{RET}
+Display a list of all identifiers matching @var{regexp}
+(@code{xref-find-apropos}).  @xref{Looking Up Identifiers}.
+
 @item M-x tags-next-file
 Visit files recorded in the selected tags table.
 @end table
@@ -2440,25 +2440,6 @@ for the project to be available.  @xref{Tags Tables}.  
If used
 interactively, the default tag is file name of the current buffer if
 used interactively.
 
-@c Sadly, the new-and-improved Xref feature doesn't provide some
-@c of the features of the now-obsoleted tags-apropos.  I'm leaving
-@c this here to encourage enhancements to xref.el.
-@ignore
-@findex tags-apropos
-@vindex tags-apropos-verbose
-@vindex tags-tag-face
-@vindex tags-apropos-additional-actions
-  @kbd{M-x tags-apropos} is like @code{apropos} for tags
-(@pxref{Apropos}).  It displays a list of tags in the selected tags
-table whose entries match @var{regexp}.  If the variable
-@code{tags-apropos-verbose} is non-@code{nil}, it displays the names
-of the tags files together with the tag names.  You can customize the
-appearance of the output by setting the variable @code{tags-tag-face}
-to a face.  You can display additional output by customizing the
-variable @code{tags-apropos-additional-actions}; see its documentation
-for details.
-@end ignore
-
 @findex tags-next-file
   @kbd{M-x tags-next-file} visits files covered by the selected tags table.
 The first time it is called, it visits the first file covered by the
diff --git a/etc/NEWS b/etc/NEWS
index e8dde45..9031ae5 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2401,7 +2401,9 @@ When non-nil, matches for identifiers in the file visited 
by the
 current buffer will be shown first in the "*xref*" buffer.
 
 *** The etags Xref backend now honors 'tags-apropos-additional-actions'.
-You can customize it to augment the output of 'xref-find-apropos'.
+You can customize it to augment the output of 'xref-find-apropos',
+like it affected the output of 'tags-apropos', which is obsolete since
+Emacs 25.1.
 
 ** Battery