Re: Writing manuals

[Fu Yuan]

在 2021年8月19日，上午9:10，Eli Zaretskii <eliz@gnu.org> 写道：



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.

Ok

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

For ELisp functions, definitely, and I wasn’t talking about that part. For query syntax and language definition syntax, because I and tree-sitter doc are talking about the exact same thing, it is harder. I certainly rephrased, and I tried to come up with different examples. I’m just not sure if that is enough (INAL).

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.

I have it on “ts” branch.

https://github.com/casouri/emacs/blob/ts/doc/lispref/parsing.texi

Thanks

Yuan