+@item
+Etags, the command for tagging identifier definitions which is part of
+the Emacs distribution. @xref{Create Tags Table}.
+
+@item
+@acronym{GNU} GLOBAL, the source code tagging system, which provides
+the @command{gtags} command and associated utilities. @xref{Command
+Line, gtags, , global, GNU GLOBAL source code tag system}.
+
+@item
+Cscope (@uref{http://cscope.sourceforge.net/}, a tool for browsing
+source code.
+
+@item
+@acronym{GNU} IDUtils, a package for generating databases of
+identifier references and querying those databases. @xref{Top,,,
+idutils, ID database utilities}.
+
+@item
+Grep, the venerable program that searches files for lines matching
+patterns. @xref{Invoking,,, grep, GNU Grep Manual}.
+@end enumerate
+
+@noindent
+Additional tools could be supported as they become available, or as
+user extensions. Each such tool is used as a @dfn{backend} by
+commands described in this section. Each command detects which
+backends are available for the current major mode, and uses the most
+capable of the available backends, with Grep generally serving as the
+fall-back backend.
+
+@cindex tag
+The commands described here are 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 identifiers as well. In this chapter, we
+collectively refer to a reference that specifies the name of the file
+where the corresponding subunit is defined, and the position of the
+subunit's definition in that file, as a @dfn{tag}. We refer to the
+backends used by @code{xref} as @dfn{tagging backends}.
+
+@menu
+* Find Identifiers:: Commands to find where an identifier is defined
+ or referenced, to list identifiers, etc.
+* Tags Tables:: Tags table records which file defines a symbol.
+* Select Tags Table:: How to visit a specific tags table.
+@end menu
+
+@node Find Identifiers
+@subsection Find Identifiers
+
+ This subsection describes the commands that use the tagging backends
+in order to find definitions of identifiers, references to
+identifiers, and perform various queries about identifiers. With most
+backends, these definitions and references were recorded as tags in
+the database created and maintained by the backend.
+
+@menu
+* Looking Up Identifiers:: Commands to find the definition of a specific tag.
+* Xref Commands:: Commands in the @file{*xref*} buffer.
+* Identifier Search:: Searching and replacing identifiers.
+* List Identifiers:: Listing identifiers and completing on them.
+@end menu
+
+@node Looking Up Identifiers
+@subsubsection Looking Up Identifiers
+@cindex find definition of symbols
+@cindex identifier, finding definition of
+@cindex find references to symbols
+
+ The most important thing that @code{xref} enables you to do is to find
+the definition of a specific identifier.
+
+@table @kbd
+@item M-.@:
+Find definitions of an identifier (@code{xref-find-definitions}).
+@item C-M-. @var{pattern} @key{RET}
+Find all identifiers whose name matches @var{pattern}
+(@code{xref-find-apropos}).
+@item C-x 4 .@: @key{RET}
+Find definitions of identifier, but display it in another window
+(@code{xref-find-definitions-other-window}).
+@item C-x 5 .@: @key{RET}
+Find definition of identifier, and display it in a new frame
+(@code{xref-find-definitions-other-frame}).
+@item M-,
+Pop back to where you previously invoked @kbd{M-.} and friends
+(@code{xref-pop-marker-stack}).
+@end table
+
+@kindex M-.
+@findex xref-find-definitions
+ @kbd{M-.}@: (@code{xref-find-definitions}) shows the definitions of
+the identifier at point. With a prefix argument, or if there's no
+valid 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.
+
+ 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.
+
+@kindex C-x 4 .
+@findex xref-find-definitions-other-window
+@kindex C-x 5 .
+@findex xref-find-definitions-other-frame
+ Like most commands that can switch buffers,
+@code{xref-find-definitions} has a variant that displays the new
+buffer in another window, and one that makes a new frame for it. The
+former is @w{@kbd{C-x 4 .}}
+(@code{xref-find-definitions-other-window}), and the latter is
+@w{@kbd{C-x 5 .}} (@code{xref-find-definitions-other-frame}).
+
+@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
+matching of identifiers instead of symbol name matching.
+
+ 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}.
+
+@kindex M-,
+@findex xref-pop-marker-stack
+@vindex xref-marker-ring-length
+ To go back to places @emph{from where} you found 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
+where you were with @kbd{M-,}. @kbd{M-,} allows you to retrace your
+steps to a depth determined by the variable
+@code{xref-marker-ring-length}, which defaults to 16.
+
+@node Xref Commands
+@subsubsection Commands Available in the @file{*xref*} Buffer
+@cindex commands in @file{*xref*} buffers
+@cindex XREF mode
+
+ The following commands are provided in the @file{*xref*} buffer by
+the special XREF mode:
+
+@table @kbd
+@item @key{RET}
+@itemx Mouse-2
+Display the reference on the current line and bury the @file{*xref*}
+buffer.
+@item n
+@itemx .
+@findex xref-next-line
+Move to the next reference and display it in the other window
+(@code{xref-next-line}).
+@item p
+@itemx ,
+@findex xref-prev-line
+Move to the previous reference and display it in the other window
+(@code{xref-prev-line}).
+@item C-o
+@findex xref-show-location-at-point
+Display the reference on the current line in the other window
+(@code{xref-show-location-at-point}).
+@findex xref-query-replace
+@item r @var{pattern} @key{RET} @var{replacement} @key{RET}
+Perform interactive query-replace on references that match
+@var{pattern} (@code{xref-query-replace}), replacing the match with
+@var{replacement}. @xref{Identifier Search}.
+@findex xref-quit
+@item q
+Quit the window showing the @file{*xref*} buffer (@code{xref-quit}).
+@end table
+
+In addition, the usual navigation commands, such as the arrow keys,
+@kbd{C-n}, and @kbd{C-p} are available for moving around the buffer
+without displaying the references.
+
+@node Identifier Search
+@subsubsection Searching and Replacing with Identifiers
+@cindex search and replace in multiple files
+@cindex multiple-file search and replace
+
+ The commands in this section visit and search all the files listed
+in the @code{xref} backend's database, one by one. For these
+commands, the database serves only to specify a sequence of files to
+search. These commands scan all the databases starting with the first
+one (if any) that describes the current file, proceed from there to
+the end of the list, and then scan from the beginning of the list
+until they have covered all the databases in the list.
+
+@table @kbd
+@item M-?
+Find all the references for the identifier at point.
+@item M-x xref-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
+Interactively replace @var{regexp} with @var{replacement} in the names
+of all the identifiers shown in the @file{*xref*} buffer.
+@item M-x tags-search @key{RET} @var{regexp} @key{RET}
+Search for @var{regexp} through the files in the selected tags
+table.
+@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
+Perform a @code{query-replace-regexp} on each file in the selected tags table.
+@item M-x tags-loop-continue
+Restart one of the last 2 commands above, from the current location of point.
+@end table
+
+@kindex M-?
+@findex xref-find-references
+ @kbd{M-?} finds all the references for the identifier at point. If
+there's no valid identifier at point, or when invoked with a prefix
+argument, the command prompts for the identifier, with completion. It
+then presents a @file{*xref*} buffer with all the references to the
+identifier, showing the file name and the line where the identifier is
+referenced. The XREF mode commands are available in this buffer, see
+@ref{Xref Commands}.
+
+@findex xref-query-replace
+ @kbd{M-x xref-query-replace} reads a regexp to match identifier
+names and a string to replace with, just like ordinary @kbd{M-x
+query-replace-regexp}. It then performs the specified replacement in
+the names of the matching identifiers in all the places in all the
+files where these identifiers are referenced. This is useful when you
+rename your identifiers as part of refactoring. This command should
+be invoked in the @file{*xref*} buffer generated by @code{M-?}.
+
+@findex tags-search
+ @kbd{M-x tags-search} reads a regexp using the minibuffer, then
+searches for matches in all the files in the selected tags table, one
+file at a time. It displays the name of the file being searched so
+you can follow its progress. As soon as it finds an occurrence,
+@code{tags-search} returns. This command works only with the etags
+backend, and requires tags tables to be available (@pxref{Tags
+Tables}).
+
+@findex tags-loop-continue
+ Having found one match, you probably want to find all the rest.
+Type @kbd{M-x tags-loop-continue}) to resume the @code{tags-search},
+finding one more match. This searches the rest of the current buffer,
+followed by the remaining files of the tags table.
+
+@findex tags-query-replace
+ @kbd{M-x tags-query-replace} performs a single
+@code{query-replace-regexp} through all the files in the tags table. It
+reads a regexp to search for and a string to replace with, just like
+ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
+tags-search}, but repeatedly, processing matches according to your
+input. @xref{Query Replace}, for more information on query replace.
+This command works only with the etags backend.
+
+@vindex tags-case-fold-search
+@cindex case-sensitivity and tags search
+ You can control the case-sensitivity of tags search commands by
+customizing the value of the variable @code{tags-case-fold-search}. The
+default is to use the same setting as the value of
+@code{case-fold-search} (@pxref{Lax Search}).
+
+ It is possible to get through all the files in the tags table with a
+single invocation of @kbd{M-x tags-query-replace}. But often it is
+useful to exit temporarily, which you can do with any input event that
+has no special query replace meaning. You can resume the query
+replace subsequently by typing @kbd{M-x tags-loop-continue}; this
+command resumes the last tags search or replace command that you did.
+For instance, to skip the rest of the current file, you can type
+@kbd{M-> M-x tags-loop-continue}.
+
+ The commands in this section carry out much broader searches than
+the @code{xref-find-definitions} family. The
+@code{xref-find-definitions} commands search only for definitions of
+identifiers that match your string or regexp. The commands
+@code{tags-search} and @code{tags-query-replace} find every occurrence
+of the regexp, as ordinary search commands and replace commands do in
+the current buffer.
+
+ As an alternative to @code{tags-search}, you can run @command{grep}
+as a subprocess and have Emacs show you the matching lines one by one.
+@xref{Grep Searching}.
+
+@node List Identifiers
+@subsubsection Identifier Inquiries
+
+@table @kbd
+@item C-M-i
+@itemx M-@key{TAB}
+Perform completion on the text around point, using the @code{xref}
+backend if one is available (@code{completion-at-point}).
+@item M-x list-tags @key{RET} @var{file} @key{RET}
+Display a list of the tags defined in the program file @var{file}.
+@item M-x xref-find-apropos @key{RET} @var{regexp} @key{RET}
+Display a list of all known identifiers matching @var{regexp}.
+@end table
+
+@cindex completion (symbol names)
+ In most programming language modes, you can type @kbd{C-M-i} or
+@kbd{M-@key{TAB}} (@code{completion-at-point}) to complete the symbol
+at point. If there is an @code{xref} backend available, this command
+can use it to generate completion candidates more intelligently.
+@xref{Symbol Completion}.
+
+@findex list-tags
+ @kbd{M-x list-tags} reads the name of one of the files covered by
+the selected tags table, and displays a list of tags defined in that
+file. Do not include a directory as part of the file name unless the
+file name recorded in the tags table includes a directory. This
+command works only with the etags backend, and requires a tags table
+for the project to be available. @xref{Tags Tables}.
+
+@c Sadly, the new-and-improved Xref feature doesn't provide anything
+@c close to the described below features of the now-obsoleted
+@c tags-apropos. I'm leaving this here to encourage enhancements to
+@c 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 next-file
+ @kbd{M-x next-file} visits files covered by the selected tags table.
+The first time it is called, it visits the first file covered by the
+table. Each subsequent call visits the next covered file, unless a
+prefix argument is supplied, in which case it returns to the first
+file. This command works only with the etags backend.
+
+@node Tags Tables
+@subsection Tags Tables
+@cindex tags and tag tables