Re: Writing manuals

[Yuan Fu]

> On Aug 18, 2021, at 5:31 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Yuan Fu <casouri@gmail.com>
>> Date: Tue, 17 Aug 2021 20:24:55 -0700
>> Cc: emacs-devel@gnu.org
>> 
>>> No, please don't use TS-specific chapter names.  In the text, you can
>>> tell that the functions you describe require the tree-sitter library,
>>> but the chapter and section names should ideally be neutral, so we
>>> could later add stuff provided by other libraries, like LSP.
>> 
>> Ok, then can I mention tree-sitter in section titles? The tentative sections 
>> are:
>> 
>> * Language definitions::    Loading tree-sitter language definitions.
>> * Using parsers::           Introduction to parsers.
>> * Accessing nodes::         Accessing syntax nodes.
>> * Pattern matching::        Pattern matching with query patterns.
>> * Query syntax::            Introducing pattern matching query syntax.
>> * Multiple languages::      Parse buffers written in multiple languages.
>> * API correspondence::      Correspondence between C API and ELisp API.
>> * Parse a string::          Parse a single string.
>> 
>> They are all tree-sitter specific.
> 
> What's wrong with the section names you show above?

Nothing wrong, just that if we want to add manual for other parsing tools, 
there could be clashes in title: maybe LSP returns syntax nodes, too, but 
“Accessing nodes” section is all about tree-sitter nodes. But we’ll worry about 
that later, as you suggested.

Another problem I discovered when writing the manual is that, my explanation of 
the query syntax is similar to the official documentation of tree-sitter. Will 
there by copyright concerns? I’ve written the section describing query syntax, 
and I’ll write another section describing the grammar definition, these two 
sections will be similar to their tree-sitter official documentation 
counterparts, because they cover exactly the same thing.

Perhaps it is best if you can see what I’ve write and compare that with the 
official documentation. I (force) pushed the latest code to GitHub. I put the 
manual in parsing.texi. The section describing the query syntax is 
(elisp)Parsing Program Source > Pattern matching. The official documentation is 
at 
https://tree-sitter.github.io/tree-sitter/using-parsers#pattern-matching-with-queries


Yuan