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: Mon, 11 Jan 2016 21:31:18 +0200 Message-ID: <83ziwbkj5l.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> <831t9pma4e.fsf@gnu.org> <5693FDFA.2070607@yandex.ru> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1452540685 26450 80.91.229.3 (11 Jan 2016 19:31:25 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 11 Jan 2016 19:31:25 +0000 (UTC) Cc: emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jan 11 20:31:25 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 1aIiBX-0006Bj-Er for ged-emacs-devel@m.gmane.org; Mon, 11 Jan 2016 20:31:23 +0100 Original-Received: from localhost ([::1]:56469 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aIiBW-0002ze-46 for ged-emacs-devel@m.gmane.org; Mon, 11 Jan 2016 14:31:22 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:37235) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aIiBS-0002zM-Mi for emacs-devel@gnu.org; Mon, 11 Jan 2016 14:31:19 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aIiBN-000420-Tu for emacs-devel@gnu.org; Mon, 11 Jan 2016 14:31:18 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:48008) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aIiBN-00041w-R1; Mon, 11 Jan 2016 14:31:13 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:2894 helo=HOME-C4E4A596F7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1aIiBM-0002yS-5R; Mon, 11 Jan 2016 14:31:13 -0500 In-reply-to: <5693FDFA.2070607@yandex.ru> (message from Dmitry Gutov on Mon, 11 Jan 2016 22:09:46 +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:198041 Archived-At: > Cc: emacs-devel@gnu.org > From: Dmitry Gutov > Date: Mon, 11 Jan 2016 22:09:46 +0300 > > - 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. Doesn't sound right to me. This is an important command, and a good addition to the Emacs features. Leaving it out of the manual just because we cannot find a good place for it, or a good way to squeeze it into the chapter, sounds... unwise. However, ... > - 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". ... xref-find-refrerences was the least of my problems when I worked on this. It's just one command. What I needed is a coherent framework that would bring some order to this group of commands and features. > > 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. Thanks, that's what I need. If the concepts and the overall idea are good, the details will fall in place by themselves.