Re: Writing manuals

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> Date: Thu, 19 Aug 2021 08:59:32 -0700
> Cc: Emacs Devel <emacs-devel@gnu.org>
> 
> >> * 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.

My idea is to put the documentation of other APIs for the same purpose
in the same section, so there shouldn't be a clash, because there
won't be multiple sections describing similar facilities, there will
be just one.

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

Well, I can only suggest to use different wording.  Since you are
describing Lisp interfaces, some phrases will be different by
necessity, and others because we have a certain style when we describe
APIs (you should be able to pick up that style by looking in the
existing descriptions in the manual).

> 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

What is the URL for parsing.texi?  I don't think I have it.

Thanks.