Recent changes in parsing.texi

Recent changes in parsing.texi

[Eli Zaretskii]

There seems to be something missing in the new text:

  +@defun treesit-defun-at-point
  +This function returns the defun node at point, or @code{nil} if none
  +is found.  It respects @code{treesit-defun-tactic}: it returns the
  +top-level defun if the value is @code{top-level}, and returns the
  +immediate enclosing defun if the value is @code{nested}.

This mentions treesit-defun-tactic, but that variable is not
documented anywhere in the manual, and is not indexed.  It should
either be documented in this node, or in some other node with a
cross-reference from here to that other node.

In general, please remember to index every function, macro, face, and
variable unless they are in @defun/@defvar/@defmac etc., which add
index entries automatically.

Re: Recent changes in parsing.texi

[Yuan Fu]

> On Dec 24, 2022, at 11:30 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> There seems to be something missing in the new text:
> 
>  +@defun treesit-defun-at-point
>  +This function returns the defun node at point, or @code{nil} if none
>  +is found.  It respects @code{treesit-defun-tactic}: it returns the
>  +top-level defun if the value is @code{top-level}, and returns the
>  +immediate enclosing defun if the value is @code{nested}.
> 
> This mentions treesit-defun-tactic, but that variable is not
> documented anywhere in the manual, and is not indexed.  It should
> either be documented in this node, or in some other node with a
> cross-reference from here to that other node.

I'll add a FIXME to remind myself to add a cross reference when we add the user manual. I think this variable should be in the user manual since its a user configuration. (I have a list of things that should be mentioned in the user manual.)

> 
> In general, please remember to index every function, macro, face, and
> variable unless they are in @defun/@defvar/@defmac etc., which add
> index entries automatically.

I’ll keep that in mind!

Yuan

Re: Recent changes in parsing.texi

[Yuan Fu]

> 
>> 
>> In general, please remember to index every function, macro, face, and
>> variable unless they are in @defun/@defvar/@defmac etc., which add
>> index entries automatically.
> 
> I’ll keep that in mind!


I just saw your fixes, so IIUC we are supposed to add a cindex for every @code not in a @defxxx in the manual, like you did here?

+@cindex treesit-font-lock-settings
 @item
 If @code{treesit-font-lock-settings} is non-@code{nil}, it sets up
 fontification.
+
+@cindex treesit-simple-indent-rules
 @item
 If @code{treesit-simple-indent-rules} is non-@code{nil}, it sets up
 indentation.
+
+@cindex treesit-defun-type-regexp
 @item
 If @code{treesit-defun-type-regexp} is non-@code{nil}, it sets up
 navigation functions for @code{beginning-of-defun} and

Yuan

Re: Recent changes in parsing.texi

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> Date: Sun, 25 Dec 2022 01:08:50 -0800
> Cc: emacs-devel@gnu.org
> 
> I just saw your fixes, so IIUC we are supposed to add a cindex for every @code not in a @defxxx in the manual, like you did here?
> 
> +@cindex treesit-font-lock-settings
>  @item
>  If @code{treesit-font-lock-settings} is non-@code{nil}, it sets up
>  fontification.

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.

Re: Recent changes in parsing.texi

[Yuan Fu]

> On Dec 25, 2022, at 1:36 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Yuan Fu <casouri@gmail.com>
>> Date: Sun, 25 Dec 2022 01:08:50 -0800
>> Cc: emacs-devel@gnu.org
>> 
>> I just saw your fixes, so IIUC we are supposed to add a cindex for every @code not in a @defxxx in the manual, like you did here?
>> 
>> +@cindex treesit-font-lock-settings
>> @item
>> If @code{treesit-font-lock-settings} is non-@code{nil}, it sets up
>> fontification.
> 
> 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.

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?

@defvar aaa
Blah blah blah @code{bbb} blah blah.
@end defar aaa

Yuan

Re: Recent changes in parsing.texi

[Eli Zaretskii]

> 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.

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