[Emacs-diffs] master e33234a: Improve documentation of etags-related features

[Eli Zaretskii]

branch: master
commit e33234ab9f387f56b3479359371c7d14d4f9e810
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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.
---
 doc/emacs/maintaining.texi | 31 +++++++++++++++++++------------
 1 file changed, 19 insertions(+), 12 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 6a592e2..39b7144 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
address@hidden 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
address@hidden buffer, together with the files in which these
-definitions are found.  Selecting one of these candidates by typing
address@hidden@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
address@hidden)
+
+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 @address@hidden 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 @address@hidden( @dots{} \)}} in
address@hidden  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='@address@hidden/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
+--regex='@address@hidden/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/'
 @end smallexample
 
 @noindent