From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.devel Subject: Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package Date: Sun, 10 Jan 2016 06:02:42 +0300 Message-ID: <5691C9D2.7080905@yandex.ru> References: <20160109191428.26341.44105@vcs.savannah.gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1452394995 23736 80.91.229.3 (10 Jan 2016 03:03:15 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 10 Jan 2016 03:03:15 +0000 (UTC) To: emacs-devel@gnu.org, Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Jan 10 04:03:10 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1aI6Hd-0006LW-Ic for ged-emacs-devel@m.gmane.org; Sun, 10 Jan 2016 04:03:09 +0100 Original-Received: from localhost ([::1]:44984 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aI6Hc-0008MB-4b for ged-emacs-devel@m.gmane.org; Sat, 09 Jan 2016 22:03:08 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53590) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aI6HP-0008KK-MO for emacs-devel@gnu.org; Sat, 09 Jan 2016 22:02:57 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aI6HO-0003Tv-2j for emacs-devel@gnu.org; Sat, 09 Jan 2016 22:02:55 -0500 Original-Received: from mail-lb0-x230.google.com ([2a00:1450:4010:c04::230]:35812) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aI6HF-0003Sp-PX; Sat, 09 Jan 2016 22:02:46 -0500 Original-Received: by mail-lb0-x230.google.com with SMTP id bc4so238791719lbc.2; Sat, 09 Jan 2016 19:02:45 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:subject:to:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-type:content-transfer-encoding; bh=TFC4WKOigoYRgL4RRy9wHqo+5xX5otczwMllvbtyNlY=; b=jeQGovXd7AonYCgmtRMd+GIDUoIihwpJKgZEtwCfrOIfE/gmrGygoiY7rw5emUpIAL vsG8o837bomFvLrIe4nBQRBVBdCSbYaaybP2YQg6Ap3kwm9nSDeXuJgHADGwxn+cEI5m FU4DwIwJZtCTjhOVdE/aRKDkSWCccH7aZqgC/MzhRSwYSxyfagZN2sHdgT8OKSQ83cqn n8F6mqpB1HGjZMy3EcA37QiUTSSXocTBqiKJPppG+G0GoIIY1L1hXs9dp1DhyUk1gTLd 17oCCWodgIzDOirt0EU9jgkfGhz2P4gm1MD5cjQz2sYWB1h0gj5Jf+jbf65Ciq98aigB sAjQ== X-Received: by 10.112.139.38 with SMTP id qv6mr42525926lbb.36.1452394964841; Sat, 09 Jan 2016 19:02:44 -0800 (PST) Original-Received: from [192.168.1.190] ([178.252.127.222]) by smtp.googlemail.com with ESMTPSA id zm10sm20021731lbb.49.2016.01.09.19.02.43 (version=TLSv1/SSLv3 cipher=OTHER); Sat, 09 Jan 2016 19:02:43 -0800 (PST) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:43.0) Gecko/20100101 Thunderbird/43.0 In-Reply-To: X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2a00:1450:4010:c04::230 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:197943 Archived-At: Hi Eli, Thanks for doing this. I've noticed some problems, though, described below: On 01/09/2016 10:14 PM, Eli Zaretskii wrote: > +Emacs provides a unified user interface to these tools, called > +@samp{xref}. The tools supported by @samp{xref} include: > +... > +@acronym{GNU} GLOBAL, the source code tagging system, which provides > ... > +Cscope (@uref{http://cscope.sourceforge.net/}, a tool for browsing > ... > +@acronym{GNU} IDUtils, a package for generating databases of > ... > +Grep, the venerable program that searches files for lines matching > ... > +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. Sorry, this is not true, unfortunately, as things currently stand. We don't use GNU Global, Cscope, ID Utils, or Grep as xref backends. We can't "find definitions" using any of them, for example, even though the user might expect to be able to do so. The only place where the aforementioned tools are used, is in the _default_ implementation of the generic function xref-backend-references. IOW, the implementation that gets used when the current backend doesn't provide its own. > +@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}. "tagging backends"? Why not call them "Xref backends", like referred to in the Xref commentary and the docstrings? I wouldn't say that the current terminology in Xref is perfect (the name itself encroaches on info-xref.el, for instance), but introducing terms that are only used in the manual, won't help clarity. Why not submit a patch for xref.el first? > +@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. That may be true for tags-search, but that's never true for xref-find-references. If the current backend defines xref-backend-references, then we just ask it, and show the results. If it doesn't, we delegate to the first available "CEDET tool", but they do perform the regexp search, not just list the files. Then, xref-collect-references takes the list of matches and verified, for each one, whether the match begins and ends on a symbol boundary (Grep can't check that). > 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. What list? xref definitely uses one database at a time (per project root, if we're talking about the default implementation). > +@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}). The last sentence makes it seem like it goes through the xref machinery, whereas it doesn't. > +@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. This makes it seem like tags-loop-continue is applicable for use after xref-find-* commands as well. But it isn't. Maybe this command, as well as tags-query-replace, the other etags-only commands, and the related etags variables, should still remain in a separate section? > +@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}). If I understand this sentence right, it's inaccurate: xref backends don't define completion tables for buffer text. It is still governed by completion-at-point-functions. xref-backend-identifier-completion-table is only used for completion in the prompt when reading an identifier, by xref commands. > +@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. Writing this complaint in the manual, expecting it to be read by someone likely to produce enhancements to xref.el, seems rather optimistic. Please submit a feature request (or several, if they're distinct). Displaying the tags files names should be possible after the xref rendering logic becomes more flexible (and e.g. could be supplied by the backend). > mode is enabled, it tries to use the Semantic parser data for > completion (@pxref{Semantic}). If Semantic mode is not enabled or > fails at performing completion, it tries to complete using the > -selected tags table (@pxref{Tags}). If in Emacs Lisp mode, it > +available @code{xref} backend (@pxref{Xref}). Also not true. Like mentioned, we don't use xref backends for completion. Unifying in-buffer completion and xref identifier completion might be beneficial, but it's not easy to do.