Re: Writing manuals

[Fu Yuan <casouri@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 3091 bytes --]



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

[-- Attachment #2: Type: text/html, Size: 5987 bytes --]