Re: Writing manuals

[Yuan Fu <casouri@gmail.com>]

> On Aug 17, 2021, at 7:26 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Yuan Fu <casouri@gmail.com>
>> Date: Tue, 17 Aug 2021 13:08:52 -0700
>> Cc: emacs-devel@gnu.org
>> 
>>> No, "Text" is for other stuff.  I think a separate chapter, something
>>> like "Parsing Program Source".  As long as you are talking about
>>> general-purpose parsing functions, not their use for font-lock etc.
>> 
>> Ok, I would name it “Parsing Program Source with Tree-sitter”, because it isn’t a generic parsing facility, but really a tree-sitter integration.
> 
> 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. How would we later add manual for other tools like LSP? Maybe I should add a tree-sitter section and move all these into tree-sitter’s subsections? Then the structure would be like

Chapter: Parsing Program Sources
Sections: 
- tree-sitter
  - Language definitions
  - Using parsers
  ...
- LSP
- some other tool

Yuan