From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.devel Subject: Re: [Emacs-diffs] emacs-26 b1aaa72: Improve documentation of Xref Date: Mon, 12 Mar 2018 01:15:47 +0200 Message-ID: References: <20180311173926.29923.58430@vcs0.savannah.gnu.org> <20180311173928.14DD220B54@vcs0.savannah.gnu.org> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit X-Trace: blaine.gmane.org 1520810079 472 195.159.176.226 (11 Mar 2018 23:14:39 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 11 Mar 2018 23:14:39 +0000 (UTC) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:59.0) Gecko/20100101 Thunderbird/59.0 To: emacs-devel@gnu.org, Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Mar 12 00:14:35 2018 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1evAAl-0008R4-1c for ged-emacs-devel@m.gmane.org; Mon, 12 Mar 2018 00:14:35 +0100 Original-Received: from localhost ([::1]:55918 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1evACn-0003QG-Rr for ged-emacs-devel@m.gmane.org; Sun, 11 Mar 2018 19:16:41 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:57427) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1evAC7-0003Q4-NX for emacs-devel@gnu.org; Sun, 11 Mar 2018 19:16:00 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1evAC6-0002Dv-Ba for emacs-devel@gnu.org; Sun, 11 Mar 2018 19:15:59 -0400 Original-Received: from mail-wm0-x233.google.com ([2a00:1450:400c:c09::233]:55051) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1evAC0-00028h-QW; Sun, 11 Mar 2018 19:15:52 -0400 Original-Received: by mail-wm0-x233.google.com with SMTP id z81so13037976wmb.4; Sun, 11 Mar 2018 16:15:52 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:subject:to:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=eUCrfI66NfMVTjeQNhHmuSHIMM6LwoNRnGSGSnupUok=; b=OxLnuhuONUstTGSoDN0jeaXBhgXDsYT8qRh6h4/knY8chYrgZlLuiRJmcSaxWC77wE RlHfV3CFzcWvqJYmaESteHTgwD+qP08eosqPLuE9kzLempahX2Pszn1GFdFuem0NS+ss r8QwOQ9I8X6yH3NItMHwLO7NZ5o83mzK5nWva40eUDvAKda2VjAsstVf7xnsPeddHxyQ J7Twi64wPbqtOQEfV12jts16oUCwhHgBPNscIufdNc/H9Pc7yUfwWOkRLlLKOWw44TXn ulGMxJ1300BM5VZHDaoE0x+SXyL6xXNA6kp/pRZTCW5XSrJQmxXpKGp+f0J8mBPSvLl0 ausg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:subject:to:references:from:message-id :date:user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=eUCrfI66NfMVTjeQNhHmuSHIMM6LwoNRnGSGSnupUok=; b=UCwL3LFq/XrVkRhLN3/JZpA/yLbEtp20y5+jOAmdQ6W8nJvCfN+CMbqDQuEfHjBTAD ZqsDm+vCJCN2kpVrmk6QTrdQmAzQHN5KK7S+BeDOfTr+BaxAd02H9wYKUtbry7BZtO5c gS7lf+dvFVx5w2PmH0AjmFgVjo+tq426LE4vB5ImbXL+20f8OxLdFd3Y4n7nV3BW+H2E 5/DSq98OxwJJ46CRJb6rxH6dtO5YaZWh6YeHPTlnf+ZrRosYjI/oYAkWpHZOi8eNCtVZ gytAyygW22TmiQ3BRYS5uI23VpB9aa6jWsc854HyQP4jy36jFnJzKCPqiEjJCgcDeq7k rqPQ== X-Gm-Message-State: AElRT7FpIlxgel/zz2kicwR6p8DQqZgg+XKt8x/+ysrYQrD80jgb9dVl 5UyX3s5zKW5YqF6ZBEVQoEP+upg3 X-Google-Smtp-Source: AG47ELtdVKI6em58YIcr6xMk+J4ph4s0QiQvaC3L9Lptutk7WmNcD3nL7x3L9f1Oh/TT/CL5fEMV3A== X-Received: by 10.28.197.205 with SMTP id v196mr3705758wmf.141.1520810151175; Sun, 11 Mar 2018 16:15:51 -0700 (PDT) Original-Received: from [192.168.1.3] ([185.105.174.23]) by smtp.googlemail.com with ESMTPSA id u127sm4660253wmd.30.2018.03.11.16.15.48 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sun, 11 Mar 2018 16:15:49 -0700 (PDT) In-Reply-To: <20180311173928.14DD220B54@vcs0.savannah.gnu.org> Content-Language: en-US X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:400c:c09::233 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 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" Xref: news.gmane.org gmane.emacs.devel:223629 Archived-At: Hi Eli, On 3/11/18 7:39 PM, Eli Zaretskii wrote: > branch: emacs-26 > commit b1aaa72df8e0afd8a849aab7525640f1cec66af3 > Author: Eli Zaretskii > Commit: Eli Zaretskii > +@findex xref-etags-mode > + Some major modes install @code{xref} support facilities that might > +fail to find certain identifiers. For example, in Emacs Lisp mode > +(@pxref{Lisp Eval}) @kbd{M-.} will by default find only functions and > +variables from Lisp packages that are loaded into the current Emacs > +session. To find more identifiers, turn on the Xref Etags minor mode > +with @w{@kbd{M-x xref-etags-mode}}. This command forces @code{xref} > +to use the @code{etags} backend (@pxref{Xref}). (For this to work, > +you should first run @command{etags} to create the tags table, see > +@ref{Create Tags Table}.) I think that's unfair to all the non-etags Xref backends, both built-in and third-party ones. "Some ... might fail to find", "to find more indentifiers" imply that etags always has a bigger and more comprehensive index. Which is not entirely true even for the emacs-lisp-mode xref backend. For instance, it will navigate to the functions defined inside any of the ELPA packages the user has installed. For the etags backend to index them, the user has to know to create a tags table there and visit it, which is not something many of users tend to do. More importantly, I think the Reddit user's problem (which has probably resulted in this manual update) was that they thought, for some reason, that xref-find-definitions will always use the tags table. And that them visiting it should affect what xref-find-definitions finds. So if there's some place in the manual that leaves them with that impression, I think it should be updated. Note that even if the current xref backend were using a system that has an all-around more comprehensive index (like GNU Global, or one of the LSP servers, etc), the user would still have a problem if they expected M-x visit-tags-table to update that index. So how about something like this: Some major modes install @code{xref} support facilities that use a different index than the current tags table. For example, in Emacs Lisp mode (@pxref{Lisp Eval}) @kbd{M-.} will by default search among the functions and variables from Lisp packages that are loaded into the current Emacs session. To consult the tags table instead, turn on the Xref Etags minor mode with @w{@kbd{M-x xref-etags-mode}}. This command forces @code{xref} to use the @code{etags} backend (@pxref{Xref}). (For this to work, you should first run @command{etags} to create the tags table, see @ref{Create Tags Table}.) ?