Re: Recent changes in parsing.texi

[Eli Zaretskii <eliz@gnu.org>]

> From: Yuan Fu <casouri@gmail.com>
> Date: Sun, 25 Dec 2022 10:54:17 -0800
> Cc: emacs-devel@gnu.org
> 
> > If a symbol appears in some @defXX directive, there's no need for a
> > separate @cindex entry, since @defXX does that automatically.  (Also,
> > I mistakenly used @cindex where I should have used @vindex; fixed.)
> > 
> > I added these index entries because these variables didn't seem to
> > appear in any @defXX directive, nor had any existing index entries.
> > If I missed something, please tell.
> 
> Thanks, I was actually just asking for confirmation of my understanding. Because my impression of vindex was that they mark the paragraph introducing and defining the variable. Basically you need to add it if you use a plain paragraph instead of defar to introduce that variable. And your change seem to imply we need to index every occurrence of a variable.

The @vindex marks the place where the variable is documented to its
fullest.  There should be just one such place, and all the other
places where the variable is mentioned should have cross-references to
that full description.  With one exception: if you document some very
special and particular aspect of the variable in a different place,
that place should have its own @vindex qualified by the aspect.  For
example:

  @vindex foobar@{, using in empty buffers}

(You need the @r{..} thingy in @vindex and @findex because otherwise
the entire text of these index entries is typeset as if it were in
@code; @cindex doesn't need @r{..}.

> Just to clarify, do I need to add @vindex bbb in the following case? (Ie, do I need to index every occurrence of a variable, or do I only need to index where it is defined?

Only index the full description of the variable, of which there should
be just one in the entire manual.  If there's no description, then
index the best approximation to it, i.e. the one place where you say
the most about it.