bug#64018: 29.0.91; Improve tree-sitter docs

[Basil Contovounesios]

Eli Zaretskii [2023-06-13 09:31 -0400] wrote:

> But on second thought: why do you need the colon at all?  What does it
> signifiy?  If you must say that KEYWORD begins with a colon, just say
> that (although it's pretty clear), or maybe show an example.

I added a colon in this single instance for consistency with subsequent
paragraphs of the same function definition:

     It takes a series of QUERY-SPECs, where each QUERY-SPEC is a QUERY
     preceded by zero or more KEYWORD/VALUE pairs.  Each QUERY is a
                              ^^^^^^^
     tree-sitter query in either the string, s-expression or compiled
     form, or a function.

     If QUERY is a tree-sitter query, it should be preceded by two
     :KEYWORD/VALUE pairs, where the ‘:embed’ keyword specifies the
     ^^^^^^^^
     embedded language, and the ‘:host’ keyword specified the host
     language.

     [...]

     If QUERY is a function, it doesn’t need any :KEYWORD and VALUE
                                                 ^^^^^^^^
     pair.  It should be a function that takes 2 arguments, START and
     END, and sets the ranges for parsers in the current buffer in the
     region between START and END.  It is fine for this function to set
     ranges in a larger region that encompasses the region between START
     and END.

The same @var{:keyword}/@var{value} pattern also appears a couple of
times in the related '(elisp) Parser-based Font Lock'.

I don't mind what we go with, so long as it's used consistently across
paragraphs of the same definition.  Which markup/wording do you prefer?

Thanks,

-- 
Basil