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

[Eli Zaretskii <eliz@gnu.org>]

> Cc: emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Tue, 19 Jan 2016 01:18:20 +0300
> 
> On 01/18/2016 08:31 PM, Eli Zaretskii wrote:
> > I tried to improve the manual according to your comments, please have
> 
> Thank you, Eli. I think it's good now, but see a couple of nits below.
> 
> > a look.  (I suggest to read the Info manual, not look at the diffs.)
> 
> I did that too, after some usual (for me) flailing around, to find the 
> needed node in the manual. The diff turned out to be more useful, 
> though, because I was able to quickly see what was removed, and what was 
> changed.

Some of the discussion we had before was about the structure of this
section.  You cannot see the structure from the diffs, which is why I
suggested to read the formatted manual.

>  > If there is a tags table loaded, this command can use it to
> +generate completion candidates more intelligently.
> 
> That implies that we have some "dumber" completion sources than etags in 
> Emacs. I don't think we do, currently. tags-completion-at-point-function 
> is the default value of completion-at-point-functions, and we use it as 
> the last resort if the major mode (or any minor mode) don't provide any 
> specialized completion functions. Then, if no tags table is loaded, we 
> don't provide any completions at all, not even stupid ones. I'd suggest 
> to simply remove "more intelligently".

Thanks, I tweaked that text some more.

>  > +  A @dfn{tag} is a synonym for identifier reference.  @xref{Xref}.
> 
> Maybe that's technically true, but as employed by Emacs usually, tags 
> are elements of TAGS file, generated by the 'etags' program, and they 
> only reference identifier definitions.

The manual in its previous form said:

  A "tag" is a reference to a subunit in a program or in a document.

This is now replaced with

  An "identifier" is a name of a syntactical subunit of the program...

So in this regard, a "tag" is indeed a synonym for "identifier".
There's nothing that can prevent recording references in tags table
format.

In any case, changing terminology in that subsection means a serious
rewrite of it in its entirety.  I see no reason for such an effort.  I
moved the offending sentence to a footnote (with some explanation why
we change terminology in this subsection), so people who already know
what "tag" is will need not stumble upon this.

Thanks.