From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii 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 22:51:13 +0200 Message-ID: <831t9pma4e.fsf@gnu.org> 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> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1452459095 22138 80.91.229.3 (10 Jan 2016 20:51:35 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 10 Jan 2016 20:51:35 +0000 (UTC) Cc: emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Jan 10 21:51:20 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 1aIMxL-000434-83 for ged-emacs-devel@m.gmane.org; Sun, 10 Jan 2016 21:51:19 +0100 Original-Received: from localhost ([::1]:49318 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aIMxK-0004BV-GJ for ged-emacs-devel@m.gmane.org; Sun, 10 Jan 2016 15:51:18 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:49439) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aIMxH-00048e-1s for emacs-devel@gnu.org; Sun, 10 Jan 2016 15:51:16 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aIMxD-0005u3-Rf for emacs-devel@gnu.org; Sun, 10 Jan 2016 15:51:14 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:50399) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aIMxD-0005ts-Np; Sun, 10 Jan 2016 15:51:11 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:1545 helo=HOME-C4E4A596F7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1aIMxB-0000su-QO; Sun, 10 Jan 2016 15:51:11 -0500 In-reply-to: <5692B1E0.8010100@yandex.ru> (message from Dmitry Gutov on Sun, 10 Jan 2016 22:32:48 +0300) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e 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:198000 Archived-At: > Cc: emacs-devel@gnu.org > From: Dmitry Gutov > Date: Sun, 10 Jan 2016 22:32:48 +0300 > > Elisp backend is one of the two Xref backends we have. The rest of the > "backends" you've described, are "external tools", which are used in a > different way than "proper" Xref backends. > > So I want the Elisp Xref backend to continue to be called an Xref > backend, but I don't want GNU Global called that, until we actually have > an Xref backend for it. Can you propose an alternative conceptual framework for the user manual, wrt to backends and the features described in this section? Here are the problems I bumped into when I worked on this section: . 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. . 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? . 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? . 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? 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? It is futile to argue about minor details if we disagree about the basics. If you can propose a coherent alternative for describing these features, maybe we can make some progress. Otherwise, I will fix the few specific minor aspects that you've pointed out, and then I will quickly try to forget about this ungrateful job I took upon myself. Thanks for the other comments, I will get to them in due time.