Re: Recent changes in parsing.texi

[Yuan Fu <casouri@gmail.com>]

> On Dec 25, 2022, at 11:02 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> 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.

Thanks a bunch! I fully understand it now.

Yuan