Improve documentation of etags-related features

* doc/emacs/maintaining.texi (Looking Up Identifiers): Document
'xref-prompt-for-identifier'.  (Bug#28403)
(Etags Regexps): Document \D back references in etags regexps.

1 files changed, 19 insertions, 12 deletions

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 6a592e2d51a..39b71445941 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1820,17 +1820,21 @@ Go back to where you previously invoked @kbd{M-.} and friends
 
 @kindex M-.
 @findex xref-find-definitions
+@vindex xref-prompt-for-identifier
   @kbd{M-.}@: (@code{xref-find-definitions}) shows the definitions of
 the identifier at point.  With a prefix argument, or if there's no
-identifier at point, it prompts for the identifier.  If the
-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 a
-@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.
+identifier at point, it prompts for the identifier.  (If you want it
+to always prompt, customize @code{xref-prompt-for-identifier} to
+@code{t}.)
+
+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 a @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.
 
   When entering the identifier argument to @kbd{M-.}, the usual
 minibuffer completion commands can be used (@pxref{Completion}), with
@@ -2430,8 +2434,11 @@ needed to recognize what you want to tag.  If the syntax requires you
 to write @var{tagregexp} so it matches more characters beyond the tag
 itself, you should add a @var{nameregexp}, to pick out just the tag.
 This will enable Emacs to find tags more accurately and to do
-completion on tag names more reliably.  You can find some examples
-below.
+completion on tag names more reliably.  In @var{nameregexp}, it is
+frequently convenient to use ``back references'' (@pxref{Regexp
+Backslash}) to parenthesized groupings @w{@samp{\( @dots{} \)}} in
+@var{tagregexp}.  For example, @samp{\1} refers to the first such
+parenthesized grouping.  You can find some examples of this below.
 
   The @var{modifiers} are a sequence of zero or more characters that
 modify the way @command{etags} does the matching.  A regexp with no
@@ -2479,7 +2486,7 @@ following example tags the @code{DEFVAR} macros in the Emacs source
 files, for the C language only:
 
 @smallexample
---regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
+--regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/'
 @end smallexample
 
 @noindent