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: 'xref' should be documented Date: Sun, 26 Apr 2015 17:57:45 +0300 Message-ID: <83618jx7h2.fsf@gnu.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1430060306 4098 80.91.229.3 (26 Apr 2015 14:58:26 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 26 Apr 2015 14:58:26 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Apr 26 16:58:16 2015 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 1YmO0d-0003Tt-8Q for ged-emacs-devel@m.gmane.org; Sun, 26 Apr 2015 16:58:15 +0200 Original-Received: from localhost ([::1]:51044 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YmO0c-0000qf-CG for ged-emacs-devel@m.gmane.org; Sun, 26 Apr 2015 10:58:14 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38420) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YmO0Q-0000oX-Km for emacs-devel@gnu.org; Sun, 26 Apr 2015 10:58:03 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YmO0N-0005AJ-Dw for emacs-devel@gnu.org; Sun, 26 Apr 2015 10:58:02 -0400 Original-Received: from mtaout24.012.net.il ([80.179.55.180]:45357) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YmO0N-0005A2-5o for emacs-devel@gnu.org; Sun, 26 Apr 2015 10:57:59 -0400 Original-Received: from conversion-daemon.mtaout24.012.net.il by mtaout24.012.net.il (HyperSendmail v2007.08) id <0NNF0050053HMC00@mtaout24.012.net.il> for emacs-devel@gnu.org; Sun, 26 Apr 2015 17:49:09 +0300 (IDT) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by mtaout24.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0NNF0054A55XVF00@mtaout24.012.net.il> for emacs-devel@gnu.org; Sun, 26 Apr 2015 17:49:09 +0300 (IDT) X-012-Sender: halo1@inter.net.il X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 80.179.55.180 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:185911 Archived-At: I think it's high time we had the xref facilities documented, both in the user manual and in the ELisp manual. It's not good for such a high-profile feature to remain undocumented. The minimal documentation in etc/NEWS is less useful than it could be, and should IMO be improved ASAP. Here are some comments on the current text in NEWS, which I hope will be useful for improving it: First, the style is wrong: it is written as a description of how the old bindings were changed into the new ones, instead of describing the new state. For example, this text: Hence, `tags-loop-continue' is unbound. `xref-pop-marker-stack' replaces `pop-tag-mark', but uses an easier binding, which is now unoccupied (`M-,'). could be significantly improved if it simply said something like `M-.' is now bound to `xref-find-definitions' instead of `find-tag', and `M-,' is bound to `xref-pop-marker-stack' instead of `tags-loop-continue'. Second, NEWS doesn't mention `xref-etags-mode', which it should, since NEWS should say how to get back the previous behavior. It should also have more explicit information about getting all of the old behavior back, by listing key bindings that would accomplish that, but since the key bindings for `xref-find-definitions-other-window' etc. are not mentioned, the user will have to work harder than necessary to figure this out. Finally, I think NEWS should also include (in a separate section) information about Lisp-level facilities, of interest to Lisp programmers who'd want to code their own back-end. This is currently completely uncovered. TIA