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: Mon, 11 Jan 2016 22:09:46 +0300 Message-ID: <5693FDFA.2070607@yandex.ru> References: <20160109191428.26341.44105@vcs.savannah.gnu.org> <5691C9D2.7080905@yandex.ru> <83egdpmo1j.fsf@gnu.org> <56929D6F.2050508@yandex.ru> <834melmfa4.fsf@gnu.org> <5692B1E0.8010100@yandex.ru> <831t9pma4e.fsf@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 1452539405 4187 80.91.229.3 (11 Jan 2016 19:10:05 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 11 Jan 2016 19:10:05 +0000 (UTC) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jan 11 20:10:00 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 1aIhqm-0008Rk-VW for ged-emacs-devel@m.gmane.org; Mon, 11 Jan 2016 20:09:57 +0100 Original-Received: from localhost ([::1]:56389 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aIhqm-0007TA-BQ for ged-emacs-devel@m.gmane.org; Mon, 11 Jan 2016 14:09:56 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:59073) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aIhqi-0007Pe-2s for emacs-devel@gnu.org; Mon, 11 Jan 2016 14:09:53 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aIhqe-0006OL-Tx for emacs-devel@gnu.org; Mon, 11 Jan 2016 14:09:52 -0500 Original-Received: from mail-lf0-x230.google.com ([2a00:1450:4010:c07::230]:32895) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aIhqe-0006OD-JB; Mon, 11 Jan 2016 14:09:48 -0500 Original-Received: by mail-lf0-x230.google.com with SMTP id m198so72607912lfm.0; Mon, 11 Jan 2016 11:09:48 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:subject:to:references:cc:from:message-id:date:user-agent :mime-version:in-reply-to:content-type:content-transfer-encoding; bh=PnP0eo6nA5DgUbg13UGlOUx++VRChGbSuI3GW6kCjIQ=; b=Wm4Dj9QNRFPrsptEU6ZCaRMeYp1x5avUGnNJ6fI6O1SZt3v5MF6jMhwaIVq1D3rEqd HGx1sfn9Gtt3hZeJeOwJtZahb0Fu2CZVDVrGlDulTuYgL3VH6qyRAeGcCVlt672ZVixH zUsLXt/lOpOHKxPTjJ4tsuQzxwkCamRqw0TvQZhNd7AW1qCrnP10D2g9nd/eH17LfZsl vJQ1HtUkvO60/xgIf1jYvdmr3ESAKBa1ysUvJcG6ve34q2yfUC1IZpe5XXQpuQ3n34OO mvP01CJPJje8D0F8X5DpwvGgK0h6MT+W9r+JjD+SgwVVQwM84Hax0ZrUF8ydHQt3x8hO QF0A== X-Received: by 10.25.212.140 with SMTP id l134mr47854472lfg.118.1452539387791; Mon, 11 Jan 2016 11:09:47 -0800 (PST) Original-Received: from [192.168.1.190] ([178.252.127.222]) by smtp.googlemail.com with ESMTPSA id ja4sm10319732lbc.8.2016.01.11.11.09.46 (version=TLSv1/SSLv3 cipher=OTHER); Mon, 11 Jan 2016 11:09:46 -0800 (PST) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:43.0) Gecko/20100101 Thunderbird/43.0 In-Reply-To: <831t9pma4e.fsf@gnu.org> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2a00:1450:4010:c07::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:198040 Archived-At: On 01/10/2016 11:51 PM, Eli Zaretskii wrote: > Here are the problems I bumped into when I worked on this section: These don't seem too complex to me. I think I've already raised many of the below points (though not the "let's not document" one). > . It is impractical to try to ignore the existence of backends: many > functions and commands mention them in their names and doc strings, > so the fact of their existence is pretty much into the user's face. > I couldn't ignore them. When the xref functions and commands mention the word "backend", they refer to xref backends. And I don't suggest we ignore them. > . There are only 2 proper backends, but then there are "fallbacks", > like symref, Grep, etc. that are used in important commands. What > do we call those "non-backends", and how do we describe them > without confusing the heck out of the readers? Again, they're only used in one command. And the way they're used, is unlikely to be extended to other commands. In the future, we may have either individual backends based on these tools, or maybe one aggregated "external tools" backend that will dispatch to the appropriate tool, if they provide more or less the same functionality. Now, using the same word, backend, for both actual Xref backends and the "external tools" feature we've borrowed from CEDET is my main complaint. Even if we only deal with that, I'll be much happier. First and foremost, do not list Etags, GNU GLOBAL, Cscope, IDUtils and Grep together. As much as we want it to be true, Emacs does not really provide a "unified user interface to these tools" (but hopefully, will sometime). I see, basically, two options: - Do not mention the external tools at all here. Only list Etags and Emacs Lisp as Xref backends. As a consequence, do not document xref-find-references in the manual. Since it doesn't replace any particular pre-existing feature, I think we're allowed to do that. - Only mention the "external tools" in the documentation of xref-find-refrerences. Maybe add a reference there to some other node. That node might have to be created, and it would list them, and contain some other guidance, like "if you're using any of those except Grep, refreshing the database is up to you". Maybe you can choose to simply refer to (info "(semantic) SymRef") there, which mentions them (and calls them "symbol reference tools"). I think that description is too short, however. > . How to describe a bunch of related features, of which only part is > implemented by Xref, the rest are still (and probably always will > be) in Etags, Semantic, etc.? How to describe commands whose > results could be very different depending on the backend and on the > major mode? The features implemented by Semantic should be described separately--it has its own manual. I'm not sure which feature of Semantic in particular you feel should be documented with that of Etags. If you mean completion-at-point, which is enhanced a bit when semantic-mode is on, then I don't see why you have to mention it. Yes, it might improve accuracy, but the user interface is the same. You can add a reference to a node in Semantic's manual that describes the benefits it adds to completion-at-point. Or could, if that node existed. Regarding the features implemented by Etags, some of which are not covered by Xref: let's make a list of the essential omissions, and try to cover them. For instance, tags-query-replace has an alternative in project[-or-external]-find-regexp, followed by xref-query-replace. dired-do-search, likewise, could be substituted for a new dired-find-regexp command which uses xref's presentation. dired-do-query-replace-regexp--with using the same command followed by xref-query-replace. I'm not saying they will be perfect, but they *will* essentially cover the same functionality. And maybe someone somewhere will be surprised to know that find-grep-dired + dired-do-query-replace-regexp is not the only way to perform replacements across all files in a directory. > . How to make all of this reasonably future-proof, given that the > functionality implemented today covers only a small portion of the > turf it was supposed to? I know it covers a small portion, but why is that a problem? We can document some existing xref commands (thus promising to maintain them), and we'll get to the rest of the functionality when it arrives. > Faced with these challenges, I came up with the solution that is now > before your eyes. What alternative do you suggest? Can you present a > coherent conceptual framework for describing these features, and a > structure of the section to go with that framework? I can try.