Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package

[Stephen Leake]

Eli Zaretskii <address@hidden> writes:

>> Cc: address@hidden
>> From: Dmitry Gutov <address@hidden>
>> Date: Thu, 21 Jan 2016 06:28:51 +0300
>> 
>> On 01/20/2016 07:43 AM, Eli Zaretskii wrote:
>> 
>> > "Xref" is the name of the node, not of the section.  And the node's
>> > name does not mean it describes xref the package; this is user-level
>> > documentation.  If you have a better suggestion for a short name of a
>> > node which aims at describing features most of which have "xref-" in
>> > their names, please tell.
>> 
>> Cross-Referencing? A native speaker might have a better suggestion.
>
> Cross-Referencing doesn't fit, IMO, not if you consider the user-level
> functionality.  

"Cross-reference" was certainly the initial intent of the xref package.

If that name no longer fits, it means there is functionality in
xref that doesn't belong there.

What operations currently in xref don't fit "cross referencing"? I
searched for "interactive" in xref.el to get a list of user-level
commands. Most were clearly related to cross references; the following
could be questioned:

xref-pop-marker-stack, xref-push-marker-stack

    Marginal; the xref UI clearly needs this functionality, but so does
    any operation that produces a list of references (like compile,
    grep, etc). It was moved here from tags-*; better would have been to
    move it to a more neutral place.

xref-query-replace

    This operates on the current list of refs, so it makes sense in xref

xref-find-apropos

    This is just a search, not relying on any "cross reference"
    information.

    project-find-* provides the same functionality, so xref-find-apropos
    can be removed (assuming every xref backend provides a project
    backend).


A short phrase descibing xref could be "operations to produce and
operate on a list of cross-references", and "cross-reference" would be a
reasonable section name.

-- 
-- Stephe