Re: Recent changes in parsing.texi

[Yuan Fu]

> 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