From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.devel Subject: Re: master b02c9bc: Improve documentation of new Xref options Date: Tue, 7 Sep 2021 18:21:24 +0300 Message-ID: References: <20210907130400.31609.90502@vcs0.savannah.gnu.org> <20210907130401.D074320A10@vcs0.savannah.gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="558"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.13.0 To: emacs-devel@gnu.org, Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue Sep 07 17:23:50 2021 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1mNcwv-000AXH-46 for ged-emacs-devel@m.gmane-mx.org; Tue, 07 Sep 2021 17:23:49 +0200 Original-Received: from localhost ([::1]:40506 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mNcwt-0002sk-W5 for ged-emacs-devel@m.gmane-mx.org; Tue, 07 Sep 2021 11:23:48 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:43824) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mNcuh-0007q0-4e for emacs-devel@gnu.org; Tue, 07 Sep 2021 11:21:31 -0400 Original-Received: from mail-wm1-x330.google.com ([2a00:1450:4864:20::330]:55892) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mNcue-0006mp-Tf; Tue, 07 Sep 2021 11:21:30 -0400 Original-Received: by mail-wm1-x330.google.com with SMTP id g135so7139688wme.5; Tue, 07 Sep 2021 08:21:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=sender:subject:to:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=FUGqjCAGs3ZhcmDT9g3HKGDSsP7cVqMWgIVUxsTtNZA=; b=cqonYt+qnZw5VPjEhNyc4cMs4+s6RHAyKzn9YgJ7FZ+dBiNF7XNGZcGDk5VJDD6t1j AjZ/Ym1koUuPuxU1yplDIP+zloZz8+B6kzQHYbdFmQBYkBzYtBR+4NfZJAjXwjEBDIbQ MYNYASNBX2+Oa/6Pkm82KMPrkXGZrZahonnAsGcUaonMDZNhxAhwfYlm1G+umdhudCgJ Yr1e3VDSOgnb1+IQT+vquFWd54doYN48XW6k6cWMnn8hFYisM+P3cCI3kTgUCVMl426j 5iitbuJzQUHI5AeRnkl3twlfsR7huATVm8tTZMz+u8jbF/V+lhroOit+Lx/OHX2pBsac Ru4w== 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=FUGqjCAGs3ZhcmDT9g3HKGDSsP7cVqMWgIVUxsTtNZA=; b=mTxUZvVO2QFrtDG76YehqheHB3+dmXtHUH4klmaF6wky01l80+lV2G8Ehse6L+wwDY B/HQKhBi7yUEtPtBUfDLBppFiSGmZMetugOq+d1HVtKimmEcQLBmjT7tadhRFEKvGi1g bqnQ9VzdJPDrdREsWGi+NhHhSHQaPMLJdQ8RHufngkmsiEFAvxwLN4aUoGtvYmkZZKx8 Rp3AysL44rMmwFtdMh21Ey+eO2XhSZ2VYkm14aY9rzkFqf6DLDWokAj5S0EVVKxY2/i5 zpXnmhIaes1xjGDXVybj6JJkjHF/zOo+blMQ8M9LfY+Lp44nscf9/+0zg5RApLBiKqsV B9aA== X-Gm-Message-State: AOAM531SCGm5r1fxBcLSMWlaKihITjn1NHQWTdltF8NAmf6IbcNvFlf+ xUf1mYOclCGOeHRFJdqKqrBko/XBT5c= X-Google-Smtp-Source: ABdhPJyzT6lB/qGAMKrTTO5mVHsHc4dm++k2hbgVZJ9m9yfY14VMfPTPsCHJ3yhP8T4CqSD9hmQrBg== X-Received: by 2002:a05:600c:2295:: with SMTP id 21mr4510717wmf.84.1631028087143; Tue, 07 Sep 2021 08:21:27 -0700 (PDT) Original-Received: from [192.168.0.6] ([46.251.119.176]) by smtp.googlemail.com with ESMTPSA id d5sm11483796wra.38.2021.09.07.08.21.25 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Tue, 07 Sep 2021 08:21:26 -0700 (PDT) In-Reply-To: <20210907130401.D074320A10@vcs0.savannah.gnu.org> Content-Language: en-US Received-SPF: pass client-ip=2a00:1450:4864:20::330; envelope-from=raaahh@gmail.com; helo=mail-wm1-x330.google.com X-Spam_score_int: -37 X-Spam_score: -3.8 X-Spam_bar: --- X-Spam_report: (-3.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FORGED_FROMDOMAIN=0.25, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.249, NICE_REPLY_A=-2.332, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 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-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:274247 Archived-At: Thanks for the updates, some comments: On 07.09.2021 16:04, Eli Zaretskii wrote: > @findex project-search > - @kbd{M-x project-search} is an interactive variant of > + @kbd{M-x project-search} is an incremental variant of Is it really incremental? Maybe call it "iterative". Compared to isearch (which is "incremental search"), we are not allowed to change the search string on-the-fly, for example. > -@c Sadly, the new-and-improved Xref feature doesn't provide anything > -@c close to the described below features of the now-obsoleted > -@c tags-apropos. I'm leaving this here to encourage enhancements to > -@c xref.el. > +@c Sadly, the new-and-improved Xref feature doesn't provide some > +@c of the features of the now-obsoleted tags-apropos. I'm leaving > +@c this here to encourage enhancements to xref.el. Is that about the display of tag file names in the apropos output buffer? TBH I'm only reading this paragraph now. A bug report with a fuller explanation might help (no promises, though, sorry). > --- a/etc/NEWS > +++ b/etc/NEWS > @@ -2309,13 +2309,18 @@ before navigating to the selected location. > +++ > *** New user options to automatically show the first Xref match. > The new user option 'xref-auto-jump-to-first-definition' controls the > -behavior of 'xref-find-definitions' and related commands: if it's t or > -'show', the first match is automatically displayed; if it's 'move', > -point in the "*xref*" buffer is automatically moved to the first match > -without displaying it. > -The new user option 'xref-auto-jump-to-first-xref' changes the behavior of > -all Xref commands in the same way as 'xref-auto-jump-to-first-definition' > -affects the "find-definitions" commands. > +behavior of 'xref-find-definitions' and related commands, like Maybe "similar" rather than related? The point is that those commands use the same UI (to show, sometimes, very different information), rather than that are united by subject matter. > +'xref-find-definitions-other-windo': if it's t or 'show', the first Typo: windo -> window > +match is automatically displayed; if it's 'move', point in the > +"*xref*" buffer is automatically moved to the first match without > +displaying it. > +The new user option 'xref-auto-jump-to-first-xref' changes the > +behavior of Xref commands such as 'xref-find-references', > +'xref-find-apropos', and 'project-find-regexp', which are expected to > +display many match that the user would like to > +visit. 'xref-auto-jump-to-first-xref' changes their behavior muuch in Typo: muuch > +the same way as 'xref-auto-jump-to-first-definition' affects the > +"find-definitions" commands. > > *** New user options 'xref-search-program' and 'xref-search-program-alist'. > So far 'grep' and 'ripgrep' are supported. 'ripgrep' seems to offer better > diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el > index d022baaf..f6d88e1 100644 > --- a/lisp/progmodes/xref.el > +++ b/lisp/progmodes/xref.el > @@ -420,7 +420,9 @@ elements is negated: these commands will NOT prompt." > "If t, `xref-find-definitions' always jumps to the first result. > `show' means to show the first result's location, but keep the > focus on the Xref buffer's window. > -`move' means to only move point to the first result." > +`move' means to only move point to the first result. > +This variable also affects commands similar to `xref-find-definitions', > +such as `xref-find-definitions-other-window'." I would call them "variations", rather than separate commands, probably. This is in contrast to xref-find-references and xref-find-apropos actually being similar while being different commands. > :type '(choice (const :tag "Jump" t) > (const :tag "Show" show) > (const :tag "Move point only" move) > @@ -429,13 +431,16 @@ focus on the Xref buffer's window. > :package-version '(xref . "1.2.0")) > > (defcustom xref-auto-jump-to-first-xref nil > - "If t, xref commands always jump to the first result. > + "If t, `xref-find-references' always jumps to the first result. > `show' means to show the first result's location, but keep the > focus on the Xref buffer's window. > `move' means to only move point to the first result. > +This variable also affects commands similar to `xref-find-definitions', similar to `xref-find-references' Here you call them "similar", like I suggest above. That seems like a good choice. Thanks.